Skip to content

Real Time Multiplayer

Jump to bottom
Kopfenheim edited this page Feb 1, 2018 · 4 revisions

Functions and callbacks for implementing the real-time multiplayer using Google Play Game Services.

Important note

Make sure that you enable real-time multiplayer in the Play Services project for your app in the Google Play Console. The option can be found in your linked apps.

It is recommended that you also read Google's Real-Time Multiplayer concepts to get a better understanding of how real-time multiplayer is implemented by Google Play Game Services

Functions

Creating a room

  • rtmStartQuickGame(int minAutoMatchPlayers, int maxAutoMatchPlayers, int playerRoleBitmask)

    Start a quick automatched game. No UI is shown and it is up to the game to update the UI as the players connect
    • Parameters
      • minAutoMatchPlayers: Minimum number of player required to start the real-time multiplayer game
      • maxAutoMatchPlayers: Maximum number of players that can be included in a real-time multiplayer game
      • playerRoleBitmask: Exclusive bitmasks for the automatching request. The logical AND of each pairing of automatching requests must equal zero for auto-match. If there are no exclusivity requirements for the game, this value should just be set to 0. You can use this to restrict only one player per role within any given match.
    • Returns
      • Nothing

  • rtmShowInvitePlayerUI(int minPlayers, int maxPlayers, boolean allowAutoMatch)

    Shows the default UI provided by Google Play Game Services that allows the currently signed in player to select a friend to play the game with and invite them to a match. This UI also allows you and the player to define how many players will be invited and the remaining required players will be auto-matched. All the invited players need to have joined the match before any auto-matching will be performed.
    • Parameters
      • minPlayers: Minimum number of players that the currently signed in player must select before they can start the match (not including the currently signed in player)
      • maxPlayers: Maximum number of players that can be included in a real-time multiplayer game (not including the currently signed in player)
      • allowAutoMatch: If true, the player will have the option to have any remaining player slots be automatched. If false, the auto-matching option will not be shown
    • Returns
      • Nothing

  • rtmShowWaitingRoomUI(int maxPlayersToStartGame)

    Show the default waiting room UI provided by Google Play Game Services which can be used to let the player
    • Parameters
      • minAutoMatchPlayers: Minimum number of player required to start the real-time multiplayer game
      • maxAutoMatchPlayers: Maximum number of players that can be included in a real-time multiplayer game
      • playerRoleBitmask: Exclusive bitmasks for the automatching request. The logical AND of each pairing of automatching requests must equal zero for auto-match. If there are no exclusivity requirements for the game, this value should just be set to 0. You can use this to restrict only one player per role within any given match.
    • Returns
      • Nothing

  • rtmHideWaitingRoomUI()

    Close the waiting room UI if needed. Any results from the Waiting Room UI will be ignored
    • Parameters
      • None
    • Returns
      • Nothing

Room and Participants Information

  • rtmGetAllParticipantIDs()

    Gets the participant IDs of all the players connected to the room that the currently signed in player is a part of. The participant IDs are not the same as a player ID and change from match to match. But, these participant IDs are required for uniquely identifying a player within the room.
    • Parameters
      • None
    • Returns
      • String with the participant IDs of all players connected to the room. The IDs are separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.

  • rtmGetParticipantDisplayName(String participantID)

    Get the display name of a participant connected to the room
    • Parameters
      • participantID: The participant ID of the participant whose display name you want to get
    • Returns
      • String with the display name of the particpant specified by the participant ID

  • rtmRequestParticipantIcon(String participantID, boolean hiRes)

    Start the asynchronous process of downloading a participant's icon from Google Play Game Services and saving it in the app's local storage.
    • Parameters
      • participantID: The participant ID of the participant whose icon you want to request
      • hiRes: If it is true, then the module will try to download a high-resolution version of the participant's icon if available or a standard resolution icon if the hi-res icon is unavailable. If it is false then the module tries to download the standard resolution icon.
    • Returns
      • boolean It is true if an icon is available to download for the participant and the process was started successfully. It is false otherwise.

  • rtmGetParticipantStatus(String participantID)

    Get an integer code value to represent a participant's current status in the room
    • Parameters
      • participantID: The participant ID of the participant whose status you want to know
    • Returns

      • int a code to specify the participant's status in the room. You can find the code definitions here. The code definitions are also summarized below:

          0: STATUS_NOT_INVITED_YET
  1: STATUS_INVITED
  2: STATUS_JOINED
  3: STATUS_DECLINED
  4: STATUS_LEFT
  5: STATUS_FINISHED
  6: STATUS_UNRESPONSIVE

  • rtmIsParticipantConnected(String participantID)

    Close the waiting room UI if needed. Any results from the Waiting Room UI will be ignored
    • Parameters
      • participantID: The participant ID of the participant whose connection status you want to know
    • Returns
      • boolean represting whether or not the participant is connected to the room

Invitations

  • rtmShowInvitationInbox()

    Shows the default Invitation Inbox UI provided by Google Play Game Services. The player can decide to accept or decline an invitation using this UI and a callback will be sent to your script about the player's decision

    • Parameters
      • None
    • Returns
      • Nothing

  • rtmJoinInvitation(String invitationID)

    If you recieve a callback that the currently signed in player has recieved an invitation to play a real-time multiplayer game, then you can use this method to join the room associated with that invitation ID.

    • Parameters
      • invitationID: The unique invitation ID associated with the invitation recieved by the player which is needed to let the player join the corresponding real-time multiplayer room
    • Returns
      • Nothing

  • rtmCheckForInvitation()

    Checks for an invitation in the background and sends a callback if an invitation is pending. It is only recommended to use this method at the start of the app. You don't need to actively check for any new invitations while the app is runnning because the module will automatically send a callback which you can handle in your game script.

    NOTE: During my testing this method always suggests that no invitation is available even though an invitation can be seen in the invitation UI. I have been unable to figure out how to solve it so far. So, try using this method at your own peril

    • Parameters
      • None
    • Returns
      • Nothing

Sending data

  • rtmSendReliableData(String data, String participantIDs)

    Send a reliable data packet to the specified participants in the room. You will recieve a callback once the data is sent and another callback when it is confirmed to have been recieved by a participant.
    • Parameters
      • data: The data you want to send to the specified participants. It must be below 1168 bytes (reference)
      • participantIDs: the participant IDs of all the players you want to send the data to. The IDs in the string must be separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.
    • Returns
      • Nothing

  • rtmSendReliableDataToAll(String data)

    Send a reliable data packet to all the participants in the room. You will recieve a callback once the data is sent and another callback when it is confirmed to have been recieved by a participant.
    • Parameters
      • data: The data you want to send to the specified participants. It must be below 1168 bytes (reference)
    • Returns
      • Nothing

  • rtmSendUnreliableData(String data, String participantIDs)

    Send a unreliable data packet to the specified participants in the room.
    • Parameters
      • data: The data you want to send to the specified participants. It must be below 1400 bytes (reference)
      • participantIDs: the participant IDs of all the players you want to send the data to. The IDs in the string must be separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.
    • Returns
      • Nothing

  • rtmSendUnreliableDataToAll(String data)

    Send a reliable data packet to all the participants in the room.
    • Parameters
      • data: The data you want to send to the specified participants. It must be below 1400 bytes (reference)
    • Returns
      • Nothing

Callbacks

Uses the fifth instance ID passed to init() through instanceIDsStr when initializing the module (i.e. {id for real-time multiplayer script})

Room Creation

  • _on_play_game_services_rtm_room_client_created(success,roomID)

    Called when the player tries to create a real-time multiplayer room

    • boolean success: true if the room was created successully and false otherwise
    • String roomID: The room ID for the room that was created

  • _on_play_game_services_rtm_room_client_joined(success,roomID)

    Called when the player tries to join a real-time multiplayer room

    • boolean success: true if the room was joined successully and false otherwise
    • String roomID: The room ID for the room that was joined

  • _on_play_game_services_rtm_room_client_left_room(roomID)

    Called when the player tries to leave a real-time multiplayer room

    • String roomID: The room ID for the room that the player is leaving

  • _on_play_game_services_rtm_room_all_participants_connected(success,roomID)

    Called when the all the participants in a real-time multiplayer room have connected successfully

    • boolean success: true if the room was created successully and false otherwise
    • String roomID: The room ID for the room in question

Room Status Updates

  • _on_play_game_services_rtm_room_status_room_connecting(roomID)

    Called when one or more participants have joined the room and have started the process of establishing peer connections.

    • String roomID: The room ID for the room in question

  • _on_play_game_services_rtm_room_status_auto_matching(roomID)

    Called when the server has started the process of auto-matching within the room (if applicable or needed).

    • String roomID: The room ID for the room in question

  • _on_play_game_services_rtm_room_status_peer_invited_to_room(concatenatedIDs)

    Called when one or more participants are invited to a room.

    • String concatenatedIDs: Has the participant IDs of the participants that were invited to the room. The IDs are separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.

  • _on_play_game_services_rtm_room_status_peer_declined_invitation(concatenatedIDs)

    Called when one or more participants decline the invitation to a room.

    • String concatenatedIDs: Has the participant IDs of the participants that declined the invitation to the room. The IDs are separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.

  • _on_play_game_services_rtm_room_status_peer_joined(concatenatedIDs)

    Called when one or more peer participants join a room.

    • String concatenatedIDs: Has the participant IDs of the participants that have joined the room. The IDs are separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.

  • _on_play_game_services_rtm_room_status_peer_left(concatenatedIDs)

    Called when one or more peer participant leave a room.

    • String concatenatedIDs: Has the participant IDs of the participants that left the room. The IDs are separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.

  • _on_play_game_services_rtm_room_status_connected_to_room(roomID,myParticipantID)

    Called when the client is connected to the connected set in a room. It is only called after the reqquired number of players have joined the room

    • String roomID: The room ID for the room in question
    • String myParticipantID: The participant ID of the currently signed in player within the room. This is different from the player ID and varies from match to match

  • _on_play_game_services_rtm_room_status_disconnected_from_room(roomID)

    Called when the client is disconnected from the connected set in a room.

    • String roomID: The room ID for the room in question

  • _on_play_game_services_rtm_room_status_peers_connected(concatenatedIDs)

    Called when one or more peer participants are connected to a room.

    • String concatenatedIDs: Has the participant IDs of the participants that have connected to the room. The IDs are separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.

  • _on_play_game_services_rtm_room_status_peers_disconnected(concatenatedIDs)

    Called when one or more peer participants are disconnected from a room.

    • String concatenatedIDs: Has the participant IDs of the participants that have disconnected from the room. The IDs are separated by the , delimiter. To get the delimiter you can also use the module's getDelimiter() method.

  • _on_play_game_services_rtm_room_status_p2p_connected(participantID)

    Called when the client is successfully connected to a peer participant. This is called at around the same time as the _on_play_game_services_rtm_room_status_peers_connected callback. But, this callback is called for one single participant at a time. So, if you use this callback then you wouldn't have to deal with the concated IDs of the other callback

    • String participantID: The participant ID for the participant that has connected to the room

  • _on_play_game_services_rtm_room_status_p2p_disconnected(participantID)

    Called when the client get disconnected from a peer participant. This is called at around the same time as the _on_play_game_services_rtm_room_status_peers_disconnected callback. But, this callback is called for one single participant at a time. So, if you use this callback then you wouldn't have to deal with the concated IDs of the other callback

    • String participantID: The participant ID for the participant that has disconnected from the room

Invitations

  • _on_play_game_services_rtm_invitation_received(invitationID)

    Called when the currently signed in player has been invited by some other player to play a real-time multiplayer match

    • String invitationID: The invitation ID that you need to know in order to join that multiplayer room represented by the invitation

  • _on_play_game_services_rtm_invitation_ui_invitation_accepted(invitationID)

    Called when the currently signed in player accepts an invitation that they might have received from another player. You should call rtmJoinInvitation within the callback and let the player join the multiplayer room.

    • String invitationID: The invitation ID that you need to know in order to join that multiplayer room represented by the invitation

Waiting Room UI

  • _on_play_game_services_rtm_waiting_room_ui_finished()

    Called when the waiting room UI has finished waiting and has found that all the required participants have joined the room

  • _on_play_game_services_rtm_waiting_room_ui_closed()

    Called when the currently signed in player decides to close the waiting room UI. Depending on your game, you can interpret this as the player trying to leave the room. You can call the rtmLeaveRoom() to leave the room.

  • _on_play_game_services_rtm_waiting_room_ui_left_room()

    Called when the currently signed in player explicitly decides to leave the room within the UI. The player is disconnected from the room internally so you don't have to worry about doing that.

Data Sending and Receiving

  • _on_play_game_services_rtm_reliable_message_sent(recipientId,tokenID)

    Called when a reliable message is sent by your device to another participant.

    • String recipientId: The participant ID that the message was sent to
    • String tokenID: The unique token for the message that you can keep track of within your game script. You can create an array of these token IDs in this callback and then remove a token ID from the array once it is confirmed to have been received by the recipient.

  • _on_play_game_services_rtm_reliable_message_confirmed(recipientId,tokenID)

    Called when a reliable message that you sent has been received by the other participant.

    • String recipientId: The participant ID of the participant who is confirmed to have recieved the message
    • String tokenID: The unique token for the message that you can keep track of within your game script. If you were storing these token IDs as the data was being sent then you can remove a token ID from that list in this callback.

  • _on_play_game_services_rtm_message_received(senderId,data,isReliable)

    Called when the currently signed in player receives a message from another player

    • String senderId: The participant ID of the participant in the room who sent the message
    • String data: The data within the message
    • boolean isReliable: If true, the message was sent reliably by the sender and false if it was sent unreliably

Others

  • _on_play_game_services_rtm_participant_icon_requested(participantID,folder,fileName)

    Called when the participant's icon was successfully loaded and saved to the app's local storage. See the section about "Obtaining the player's profile picture" in the Player Information page for some more info about how to use data provided by this callback.
    • String participantID: The unique participant ID of the participant for whom the icon was loaded
    • String folder: The subfolder within the user:// directory of Godot within which the image is located
    • String fileName: The name of the .png image
Clone this wiki locally