Guild Invites

Guild Invite is a mechanism for a Player in a Guild to invite other players to join their guild. All Guild Invite mechanisms contain the following steps:

1. Creation of the Invite.
2. Sharing the Invite with the target player(s).
3. Allowing the players to inspect the the invitation.
4. Using the invitation to join a guild.
5. And finally, expiration of an invite.

1. Creation of an Invite

Creation of an Invite is requested by a Player in a Guild. The player defines the type and optional arguments, such as usage limit and expiration time, and requests the creation of an Invite. The server validates the request and checks that the player has permission to invite other players.

The requirements for a player to be able to create an invite are:

• Player has less than GuildMember.MaxNumInvites active (not expired) invites.
• GuildModel.HasPermissionToInvite(inviterId, InviteCode) returns true

If these conditions are met, the server creates the Invite of the requested type. The Invite information is inserted into the GuildMember.Invites dictionary.

2. Sharing Invite with Target Players(s)

Sharing an invite is Invite method specific: For Guild Invite Codes, sharing the Invite requires the inviting player to send the invite code to the other player via some external mechanism, for example, instant messaging or posting the code to Discord.

Currently, Guild Invite Codes are the the only Invite mechanism. In particular, invites via Shared Deep Links or Sending an Invite directly to a Player's Inbox are not yet supported.

3. Inspecting the Invite

Upon receiving an Invite, the client cannot just blindly accept it. Instead, the client must first inspect the Invite to resolve:

• Whether the Invite is still valid.
• To which Guild are they being invited to: The EntityId of the Guild and the GuildDiscoveryInfo containing the game-specific information about the Guild. At a bare minimum, this contains the Name of the guild. More information can be added by extending GuildDiscoveryInfo.
• Who created the invitation: The EntityId and a GuildInviterAvatar of the inviting player. GuildInviterAvatar by default contains the name of the player and it can be extended by adding new fields and implementing PlayerActor.CreateGuildInviterAvatar.
• The InviteId of the Invite. This, along with the EntityId of the guild, uniquely identify this particular Invite.

4. Using the Invitation to Join a Guild

If the invited player is satisfied with the Invite after having inspected it, the player may attempt to use it. The exact method of using an Invite varies by invite type but they all require the InviteId to be passed.

When invite is attempted to be used, the server first validates that the Invite is still valid. If this is the case, GuildActor.ShouldAcceptPlayerJoin is called with isInvited set to true. If the method returns true the player join succeeds and the Invite is used once.

5. Expiration of an Invite

Guild Invites have an optional expiration time and an optional usage limit. When either is exceeded, the Invite expires automatically. The usage is counted only for successful usages and hence joins rejected by ShouldAcceptPlayerJoin do not count.

Additionally, when the inviting player leaves or is removed from a guild, all the player's invitations expire immediately.

DANGER

Subject to change: A player can repeatedly Join using the Invite and then Leave, and maliciously use all Invite usage limits. Metaplay does not yet implement "refunding" Invite usages if an invited player leaves.

The client may also Revoke an active Invite. This can be useful if GuildMember.MaxNumInvites limit is reached:

// inviteId is the key for GuildModel.Member[selfPlayerId].Invites[] dictionary
GuildClient.RevokeGuildInvite(inviteId)

Using Guild Invite Codes

A Guild Invite Code is a 14 character string of form "AAAA-BBBB-CCCC". The code tolerates and corrects similar-looking characters (I,l,1, and O,0) and is case-insensitive. It also has a convenience checksum embedded to detect typos already on the client.

A Guild Invite Code is created by using GuildClient.BeginCreateGuildInviteCode. For example:

// Create Invite Code for 5 days, and 10 usages
GuildClient.BeginCreateGuildInviteCode(
    expirationDuration: MetaDuration.FromDays(5),
    usageLimit: 10,
    onResponse);

When the call completes, the OnResponse callback invoked:

void OnResponse(GuildCreateInvitationResult result)
{
    if (result.Status == Success)
    {
        // Success. New invite is added to
        // GuildModel.Member[selfPlayerId].Invites[inviteId] but it is
        // also available as result.InviteState for convenience.
        ShowInUI(result.InviteState.InviteCode)
    }
    else
    {
        // Handle errors
    }
}

The player has now successfully created a Guild Invite with an Invite Code. To invite a friend or friends, the player may now share the Invite Code with them.

To accept the Invite, the invited player inputs the code into the game. The game validates that the code is well-formed by parsing it to GuildInviteCode.TryParse(string, out GuildInviteCode). TryParse automatically corrects missing separators and similar-looking characters, and accepts both upper and lower case characters. When the code is well-formed, the Client requests the server for more information about the invite:

GuildClient.BeginInspectGuildInviteCode(code, OnResponse);

The server validates that the invite is still valid and, if so, gathers Invite information for the client. onResponse is then invoked:

void OnResponse(GuildInviteInfo inviteInfo)
{
    if (inviteInfo == null)
    {
        // The invite is invalid or expired
    }
    else
    {
        // The invite is still valid: show user information about the guild.
        ShowInUI($"User: {inviteInfo.InviterAvatar.DisplayName} "
         + $"wants you to join their guild {inviteInfo.GuildInfo.DisplayName}")
    }
}

Player may now accept the invitation, and attempt to join the guild with the Invite Code. Note that the joining can still fail if GuildActor.ShouldAcceptPlayerJoin returns false or if invite has expired:

GuildClient.BeginJoinGuildWithInviteCode(
    inviteInfo.GuildInfo.GuildId,
    inviteInfo.InviteId,
    inviteInfo.InviteCode,
    OnCompletion);