👪 PartyKit

Invite friends and allow your players to play with others.

What is PartyKit?

PartyKit is Trail's own party system where players play together on the platform. Not only that, but it also provides the ability to generate a direct link to a player's session so their friends can join in -- both the game and party, instantly and without needing to install anything to run the game. On top of that, it allows party members to share and update data as long as they are members.

🚧

Trail party vs in-game party

Something to note is that a Trail party doesn't mean an in-game party. PartyKit is designed to work with a backend. This means your backend would have its own party system defined; PartyKit only deals with the information and data on the Trail platform. This means that you'll need your own system to transfer in-game data between members (i.e. updating character positions, rotations, health amount, damage, etc...).
PartyKit doesn't officially offer such a system at the moment.

What is a Trail party?

We must define what a party is in Trail before we learn how to use PartyKit. A party is a group of players in a list with one of them designated as the leader (usually the longest-standing member of the party) that allows the exchange of information between its members privately.
On Trail, any player at any given point in time is, in fact, in a party -- even if they are completely alone and not playing with someone. This sole player would be considered the party leader and no other members exist within the party.

📘

Example

Let's say we have PlayerA and PlayerB -- they are completely separate and don't know anything about each other at the moment. From the minute they both land on Trail, two parties are created and each is added to it as the leader and sole member. Now, we have PlayerA in PartyA and PlayerB in PartyB.

Let's say that PlayerA and PlayerB met up somewhere outside of Trail and got to be friends. Then PlayerA proposed they play together on Trail.

If PlayerA creates an invite link and sends it over to PlayerB and PlayerB joins, PlayerB will exit PartyB and thus, it dissolves (given no members exist anymore) and will join PlayerA as the second member of PartyA. This means that now, both PlayerA and PlayerB are in the same party; PartyA. Due to PlayerA being the longest-standing member in PartyA so far, PlayerA is considered the leader.

If PlayerA sends an invite to say UserC, who isn't a Trail user and hasn't visited Trail yet, UserC will land on Trail and join PlayerA and PlayerB in PartyA. So now, PartyA has PlayerA, PlayerB and UserC. Let's say that after that, PlayerA departs for any reason, PlayerB becomes the new leader of PartyA, given PlayerB is the longest-standing member of PartyA.

How to invite others from a player perspective

At the moment, the player that wants to invite others (we'll refer to them as inviter from now on) will create an invite link which would look like this: https://trail.gg/join/xyz123 and uses any messaging service (i.e. Discord, Slack, Skype, etc...) to send it to the people they want to invite (we'll refer to them as invitee). An inviter can simply click an in-game button similar to the below to create the invite link:

The share button that allows a player to generate an invite linkThe share button that allows a player to generate an invite link

The share button that allows a player to generate an invite link

The popup window below will appear showing the generated invite link:

The invite link after it is generated in-game.The invite link after it is generated in-game.

The invite link after it is generated in-game.

Once the receiver of the invite link clicks the link, they'll immediately be sent to a landing page that looks like the page below:

Landing page shown to incoming players.Landing page shown to incoming players.

Landing page shown to incoming players.

Once the invitee clicks Start game, the game will immediately start loading. On the other end, the inviter (as well as any member of their party) will receive updates on the invitee's status; if they started the game, how much of the game has been downloaded, if they are playing through a mandatory tutorial level, etc...
Not only that, but if the inviter invited the invitee to a specific location in-game (say the lobby), the invitee will land on that location automatically once the game is fully loaded.

A loading message from FriendlyAlpaca.A loading message from FriendlyAlpaca.

A loading message from FriendlyAlpaca.

📘

Inviting to a specific game location

You can as a developer -- as mentioned above, implement the invite so that the invitee can land in a specific location in-game (i.e. the lobby), this is done through PartyKit's PartyDataField that we'll explore later in an example.

Create an in-game invite link

The UX part of creating the link will depend on your game and the experience you want the player to go through. However, we recommend that this option is available in a location that isn't intrusive to your gameplay loop while at the same time, somewhere the player can easily access in case they decide they don't want to proceed alone.

Once you've nailed down the design aspect of it, the coding part is pretty simple:

// Remember to initialize the SDK first

public void InviteFriend()
{
  // Calling the below method will show the invite link popup shown above
  Trail.PartyKit.ShowInviteLink();
}

The above line of code will simply create the pop-up you've seen earlier and generate a link ready for the player to use.

Sending status updates to party

As mentioned, when an inviter invites someone to their session (and consequently to their party), Trail allows you to update the party members with the invitee status (pictured above); whether they accepted the invite or not, downloading the game, etc...
Trail does offer status updates outside of the game (accepted invite, downloading the game, initializing the game, etc...) out of the box. However, you're also able to send custom events specific to your game, such as "[Player Name] is playing through the tutorial!" for example.

private void OnInviteeStartedTutorial()
{
  // This will change the status message to show "[Player Name] is playing the tutorial!"
  // Note you don't need to refer to the player, PartyKit will deal with that for you
  Trail.PartyKit.UpdateInviteLoadingMessage("is playing the tutorial!");
}

Finalizing an invitee's join status

Once an invitee finally ends up in the game (i.e. downloaded the game and is in-game) or failed to do so, you need to finalize the invite's status (i.e. inform the party of the invitee's status):

private void OnInviteeJoined(string partyID, string serverRegion) 
{
  
  // Send the data to your matchmaker so the invitee can join your matchmaker's party
  bool success = MyMatchMaker.JoinParty(partyID, serverRegion);
  
  // Tell Trail that the invite is successful or not and inform party members of it.
  PartyKit.FinalizeInviteLoading(success);
  
  // You can also pass the status to your own backend and/or game in case you want to 
  // offer a "retry" button for the player.
  MyMatchMaker.HandleInvite(success);
}

The above will trigger a final message showing the status of the invite (whether the invitee was able to reach the in game location they were invited to or not) to all party members.

Sharing data between party members

Since an invite allows the invitee to join the inviter's party, this means that both players will need to exchange data. As mentioned before, an inviter could invite a player to a specific section of the game (say an in-game lobby or the first level).

Every member of the party automatically shares data with everyone else in the party. So if we have a party that consists of PlayerA, PlayerB and PlayerC; all of them will be sending data to everyone else trying to update the state of the party's data. Because of this, we've introduced the concept of a Party Leader; a member of the party that has been in the party the longest (usually it is the player that invited other players to their party). If you've worked with multiplayer games (especially P2P) this concept should sound familiar, it is very similar to the idea of a Master Client.

An illustration of how the Party Leader data can only change the party data while other change requests will be ignored.An illustration of how the Party Leader data can only change the party data while other change requests will be ignored.

An illustration of how the Party Leader data can only change the party data while other change requests will be ignored.

📘

The reason why all party members attempt to update the party data (even when we only apply the data from the Party Leader) is that parties constantly change and at any point in time, a Party Leader can leave the party and as such, the "Lead" status will change and be given to the next person in line (the next longest-standing member of the party).

Updating data is simple; first you need to create and define the data you'll update and then send it over to the party. Note, however, it is recommended that you update the data only when they change (i.e. when a player changes a scene perhaps or switches a region, etc...)

// Remember to initialize the SDK first

public void UpdatePartyData() 
{
  // Create the data fields you want to update
  var partyDataFields = new PartyKit.PartyDataField[] {
    new PartyKit.PartyDataField("partyID", "party-id-123"),
    new PartyKit.PartyDataField("serverRegion", "EU")
  };
  
  // Call the update method to send over the updates.
  Result result = PartyKit.UpdatePartyData(partyDataFields);
  
  // Check whether the update was successful or not and act accordingly.
  if (result.IsOK()){
    Debug.Log("Update party data succeeded");
  }
  else {
    Debug.LogWarningFormat("Update party data failed: {0}", result);
  }
}

📘

Note that the data being shared here doesn't mean anything will happen in the game until you act on it. For example, in the above code, you could check with your backend if the target in-game party is in the same region (perhaps the invitee is in the EU region while the inviter is in the US region), and if they are not, then you can display an error message to the user and ask them to change their region.

Meanwhile you can act on the data received by subscribing to the receiving data event (which is triggered when new data is available or the data has changed). Here is how you can do that:

// Remember to initialize the SDK first

// Subscribe to the OnPartyDataUpdated event
private void OnInit()
{
  PartyKit.OnPartyDataUpdated += OnPartyDataUpdated;
}

private void OnPartyDataUpdated()
{
  var data = PartyKit.GetPartyData();

  // Iterate over the data received (given it is a key-value pairs) to fetch what you want.
  for (int i = 0; i < data.Count; i++) {
    Debug.Log(string.Format("Entry: {0}  -  Key: {1} - Value: {2}", i, data[i].Key, data[i].Value));
    
    string value = (string)data[i].Value;
    
    if(value.Contains("EU")) {
      MyMatchMaker.SetRegion(value);
    }
  }
}

🚧

PartyKit Errors

Sometimes when checking the nature of a "Result" you may receive the following:
Result.PTKNoInviteLoading

This generally happens when you're trying to call a PartyKit method on a player that loaded without an invite. Basically, a player didn't receive an invite and just loaded the game from Trail.gg directly.

Updated 4 months ago


👪 PartyKit


Invite friends and allow your players to play with others.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.