Party-Based Gameplay Using the Social Synergy API

The Verse Social Synergy API reports a player's party membership, so you can build gameplay that responds to who a player brought with them. A party is the group a player formed in the Epic ecosystem (Fortnite, Epic Games Launcher, and Epic Games mobile apps). It is not a team, and it is not a group produced by matchmaking.

This guide provides an overview of the classes and functions in the API and example snippets for how to build social mechanics, including:

• Score bonuses for parties

• Party-only access to an area

• Difficulty that scales to party size

• Reduced friendly fire between party members

• Dynamic commentary and UI

• Party-based cosmetic visual effects (VFX)

Before You Start

To best understand the content on this page: 

• Review the Social module reference.

• Have a fundamental understanding of using Verse. To learn more, see the Verse Programming Onboarding Guide.

• Every example on this page uses a Verse device. To create one, see Create Your Own Device Using Verse.

How the Social Synergy API Works

The API includes the function GetLocalParty(), defined on the player. It returns a group object that holds the party members and the events for that party. This means that you call it on a player rather than passing a player to it. 

The group is a single value, not a list or a count. 

# An extension is called on a player, not passed on one.
Party := SomePlayer.GetLocalParty()

  To use the API, add the Social and the Agent Group modules to your using block:

using { /UnrealEngine.com/Social }
using { /Verse.org/AgentGroup }
using { /Verse.org/Simulation }

The group holds only the party members who are present in the current session. A player's party can extend beyond your island, and those members are outside the group. A player is always in a party of at least one member. The group, therefore, always contains at least one member, and a party size of 1 identifies a solo player.

The group supports these operations:

• Read who is in it. GetMemberMap() returns the members, which gives you a party size and a way to act on each member.

• React when the group changes. The group signals events. Subscribe to one and your code runs whenever a member joins or leaves.

• Compare players’ party membership. Two players in the same party receive the same group object, so comparing two results tells you whether the players are in the same party.

  For the full signature and specifiers, see the GetLocalParty page in the Social module reference.

Read a Player's Party to Gate an Area

GetMemberMap() returns a map of each party member agent to that member's party_member_info. Read Length for the party size, or iterate the keys to act on each member individually. The party_member_info value is empty, so read the keys and ignore the values.

The example below reads party size to control a barrier. When a player interacts with a button, the Verse device checks whether that player has a party member present and adds the player to the Barrier device's ignore list to grant them access. 

To build the party barrier:

1. Place a HUD Message device, a Barrier device, and a Button device on your island. Position the Button device next to the Barrier device, and leave the Barrier device enabled so that the area starts locked.

2. Create a Verse device named party_area_device with editable properties for the three devices.

   Verse

   using { /Fortnite.com/Devices }
   using { /Fortnite.com/FortPlayerUtilities }
   using { /UnrealEngine.com/Social }
   using { /Verse.org/AgentGroup }
   using { /Verse.org/Simulation }
   
   party_area_device := class(creative_device):
   
       # The Barrier device that blocks the area. Assign it in the Details panel.
       @editable
   
   Expand code Copy full snippet(19 lines long)

3. Add editable properties for the denial message and how long it stays on screen. Add the StringToMessage helper alongside them because HUD devices take a message rather than a string and the helper is not part of the standard library.  

   Verse

       # The message text to show when the area is locked.
       @editable
       NoPartyMessage:string = "You need a party member on the island to unlock this area."
   
       # How long the denial message stays on screen (in seconds).
       @editable
       MessageDisplayTime:float = 3.0
   
       # Converts a runtime string into a localizable message type required by
       # HUD devices. Declared inside the class so that every device on this
   
   Expand code Copy full snippet(12 lines long)

   Every Verse file in a folder belongs to the same module and shares one namespace, so you can declare StringToMessage at file scope in one Verse file. You can also add a module block in a shared file and import that module when you need it. See Modules and Paths in the Book of Verse.

4. Subscribe to the button's interaction event in OnBegin(). OnBegin() runs once for the device, so it registers the handler once.

   Verse

       OnBegin<override>()<suspends>:void =
           # Subscribing anywhere that runs repeatedly creates duplicate
           # handlers, and the area then runs its logic once for each one.
           BarrierButton.InteractedWithEvent.Subscribe(OnBarrierButtonPressed)

   Copy full snippet(4 lines long)

5. Add the handler. InteractedWithEvent passes an agent, and GetLocalParty() is defined on the player, so the handler casts before it reads the party.

   Verse

       OnBarrierButtonPressed(InAgent:agent):void =
           # This cast fails for a player who has left the session, and
           # the if skips the body.
           if (Player := player[InAgent]):
               # Length check is set to greater than or equal to 2, not > 0:
               # a player alone is still a party of one, so > 0 unlocks the area for everyone.
               if (Player.GetLocalParty().GetMemberMap().Length >= 2):
                   # Disabling the barrier opens the way through. A barrier
                   # device blocks while it is enabled, so the call is
                   # Disable() rather than Enable().
   
   Expand code Copy full snippet(15 lines long)

6. Compile your Verse code, drag the Verse device into your island, and assign the Barrier, Button, and HUD Message devices to its editable properties in the Details panel.

7. Test with two accounts in a party and confirm the area unlocks. Test with a single account to confirm that the message appears instead.

using { /Fortnite.com/Devices }
using { /Fortnite.com/FortPlayerUtilities }
using { /UnrealEngine.com/Social }
using { /Verse.org/AgentGroup }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

# See https://dev.epicgames.com/documentation/en-us/uefn/create-your-own-device-in-verse for how to create a verse device.

party_area_device := class(creative_device):

Respond When a Party Member Joins or Leaves

The group signals the following events. Each one passes a tuple(agent, party_member_info) holding the member that changed and that member's info.

The example below subscribes to AddMemberEvent and RemoveMemberEvent and shows a heads-up display (HUD) message to the affected player.

To build the notification device:

1. Place a HUD Message device on your island.

2. Create a Verse device named party_notification_device. Add a party_listener class above the device class, holding the player to notify and the values each notification needs.

   Verse

   using { /Fortnite.com/Devices }
   using { /Fortnite.com/Characters }
   using { /Fortnite.com/Devices }
   using { /Fortnite.com/Game }
   using { /UnrealEngine.com/Social }
   using { /Verse.org/AgentGroup }
   using { /Verse.org/Simulation }
   
   party_listener := class:
   
   
   Expand code Copy full snippet(29 lines long)

   This listener is a general pattern rather than something specific to notifications. Any time a callback needs to know which player it is acting for, a small class that holds the player and subscribes itself supplies that context because Verse has no closures to capture it at the subscription site. The party_listener is a plain class rather than a device, so it does not appear in the Details panel and nothing is placed in the level for it.

3. Add StartListening() to the listener. The listener subscribes itself, so both callbacks are references to its own methods.

   Verse

      StartListening():void =
           # One call, two subscriptions: both events live on the same group object.
           Party := TargetPlayer.GetLocalParty()
           Party.AddMemberEvent.Subscribe(OnMemberAdded)
           Party.RemoveMemberEvent.Subscribe(OnMemberRemoved)

   Copy full snippet(5 lines long)

4. Add the two handlers. Each receives a tuple holding the member that changed.

   Verse

       OnMemberAdded(MemberInfo:tuple(agent, party_member_info)):void =
           # Element 0 is the agent that changed.
           # Element 1 is their party_member_info, which is empty.
           JoinedAgent := MemberInfo(0)
           HUD.Show(TargetPlayer, StringToMessage(JoinText), ?DisplayTime := ShowTime)
   
       # Mirrors OnMemberAdded. Element 0 is the agent that left.
       OnMemberRemoved(MemberInfo:tuple(agent, party_member_info)):void =
           LeftAgent := MemberInfo(0)
           HUD.Show(TargetPlayer, StringToMessage(LeftText), ?DisplayTime := ShowTime)

   Copy full snippet(10 lines long)

5. Add the device class with editable properties for the HUD Message device and the two message strings.

   Verse

    party_notification_device := class(creative_device):
   
       # The HUD Message device that shows the notifications. Assign it in the Details panel.
       @editable
       NotificationDevice:hud_message_device = hud_message_device{}
   
       # The message shown when a party member joins the session.
       @editable
       JoinedMessage:string = "A party member joined the island!"
   
   
   Expand code Copy full snippet(17 lines long)

6. In OnBegin(), cover every player already in the session, then subscribe to PlayerAddedEvent(). Players already present and players who arrive later are two separate cases.

   Verse

        OnBegin<override>()<suspends>:void =
           # Covers everyone present when the device starts.
           for (Player : GetPlayspace().GetPlayers()):
               SubscribeToPartyEvents(Player)
   
           # Covers everyone who joins after the session starts.
           GetPlayspace().PlayerAddedEvent().Subscribe(OnPlayerJoined)
   
       OnPlayerJoined(InPlayer:player):void =
           SubscribeToPartyEvents(InPlayer)

   Copy full snippet(10 lines long)

7. Add SubscribeToPartyEvents(), which builds one listener for each player and starts it. Call it only from initialization, because subscribing inside an event handler adds a further subscription every time the event fires.

   Verse

       SubscribeToPartyEvents(InPlayer:player):void =
           # Two players in the same party share a single group object, so both
           # subscriptions sit on that one object. Each fires with its own listener,
           # so each player receives one message.
           Listener := party_listener:
               TargetPlayer := InPlayer
               HUD := NotificationDevice
               JoinText := JoinedMessage
               LeftText := LeftMessage
               ShowTime := MessageDisplayTime
   
   Expand code Copy full snippet(11 lines long)

8. Compile your Verse code, place the device in your island, and assign the HUD Message device to the NotificationDevice option in the Details panel.

9. Test with two accounts in a party. Have the second account join and leave the session, and confirm that one message appears for each change.

The HUD messages can do more than announce the change. You can inform players what is now available to them, For example, a player who was turned away from the party area earlier can be told that they can now open it, which saves them walking back to find out. The same message can gate a quest, a vehicle, or any other content that needs a second player present.

using { /Fortnite.com/Devices }
using { /Fortnite.com/Characters }
using { /Fortnite.com/Devices }
using { /Fortnite.com/Game }
using { /UnrealEngine.com/Social }
using { /Verse.org/AgentGroup }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

Compare Two Players to Reduce Friendly Fire

Calling GetLocalParty() on two players in the same party returns the same group object. Comparing the two results with = therefore tests whether the players are in the same party, and compares object identity rather than member lists.

The example below scales damage between two players: party members deal reduced damage to each other, and everyone else deals full damage. It uses only a Verse device. It returns a multiplier, and your own damage code applies it, such as one with a custom Scene Graph weapon.

The modifier applies to islands where players can damage each other: Free For All, or Friendly Fire enabled through Island Settings or a Team Settings and Inventory device.

To build the damage modifier:

1. Create a Verse device named party_friendly_fire_device with editable multipliers for both cases. A party multiplier of 0.0 disables friendly fire between party members entirely.

   Verse

   using { /Fortnite.com/Devices }
   using { /UnrealEngine.com/Social }
   using { /Verse.org/AgentGroup }
   using { /Verse.org/Simulation }
   
   party_friendly_fire_device := class(creative_device):
   
       # Applied when attacker and target are in the same party. A value of 0.0
       # disables friendly fire between party members entirely.
       @editable
   
   Expand code Copy full snippet(15 lines long)

2.  Add the comparison. This tests object identity, so it compares the two group objects and ignores their member lists.

   Verse

       # <public> means other Verse devices in your project can call this.
       CalculateDamageMultiplier<public>(Attacker:player, Target:player)<transacts>:float =
           # Two players in the same party receive the same group object,
           # so = succeeds. Two players in different parties receive
           # different objects, so it fails. The comparison ignores member
           # lists, so it is safe to run on every damage event.
           if (Attacker.GetLocalParty() = Target.GetLocalParty()):
               DamageMultiplierForPartyMembers
           else:
               DamageMultiplierForNonParty

   Copy full snippet(10 lines long)

3. Compile your Verse code, place the device in your island, and set the two multipliers in the Details panel.

4. Call CalculateDamageMultiplier() from the code that applies damage, and multiply your base damage by the result. Some damage paths compare a player against themself. A player is always in a party of at least one, so a solo player's group compares equal to itself.

5. Test once the function is wired into your damage code. With two accounts in a party, confirm damage between them is reduced. With two accounts in different parties, confirm damage stays at the full multiplier.

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /Verse.org/AgentGroup }
using { /Fortnite.com/Game }
using { /UnrealEngine.com/Social }
using { /UnrealEngine.com/Temporary/Diagnostics }

# See https://dev.epicgames.com/documentation/en-us/uefn/create-your-own-device-in-verse for how to create a verse device.

# A Verse-authored creative device that can be placed in a level

More Examples

Following are additional examples for size, event, and identity operations. 

Grant One Bonus for Party Play and Another for Solo Play

A party size of one identifies a solo player, so a single check controls both branches. Players in a party get a higher max health, and solo players get items instead.

using { /Fortnite.com/Characters }
using { /Fortnite.com/Devices }
using { /Fortnite.com/Game }
using { /UnrealEngine.com/Social }
using { /UnrealEngine.com/Temporary/Diagnostics }
using { /Verse.org/AgentGroup }
using { /Verse.org/Simulation }

# Applies a bonus once for each player, chosen by party size: a higher health
# ceiling for players with a party member present, items for players alone.

This device applies the bonus when a player joins the session. A player who parties up after arriving keeps the bonus they were given on arrival. To respond to that, subscribe to the party events as described in Respond When a Party Member Joins or Leaves.

Scale an Arena to the Party

This example iterates the member map rather than reading its length. It teleports every party member into an arena, then scales the encounter to the number of members who arrived.

using { /Fortnite.com/Devices }
using { /Fortnite.com/Game }
using { /UnrealEngine.com/Social }
using { /UnrealEngine.com/Temporary/Diagnostics }
using { /Verse.org/AgentGroup }
using { /Verse.org/Simulation }

# Teleports a player's party into an arena when a button is pressed,
# then enables spawners in proportion to how many members arrived.
party_battle_arena_device := class(creative_device):

You can teleport without a Teleporter device by calling TeleportTo() on each member's fort_character, and using this device's own GetTransform() as the destination, or reference the position of other objects like a prop. 

Assign Party Members to the Same Team

This example uses identity comparison to keep a party together. When a player joins, the device looks for another player in the same party and moves the new arrival onto that player's team.

The snippet assumes your island is configured with fixed teams. In Island Settings, set Teams to a specific number rather than Free For All, and provide at least as many teams as the number of separate parties you expect. 

using { /Fortnite.com/Devices }
using { /Fortnite.com/Game }
using { /Fortnite.com/Teams }
using { /UnrealEngine.com/Social }
using { /UnrealEngine.com/Temporary/Diagnostics }
using { /Verse.org/AgentGroup }
using { /Verse.org/Simulation }

# Moves a joining player onto the team their party member is already on.
party_team_assigner_device := class(creative_device):

The device activates when a player joins the session, so two players who arrive separately and party up afterward keep their original teams. To adjust for this scenario, subscribe to AddMemberEvent.

On Your Own

Extend these techniques:

• Scale rewards by party size. Multiply a score or experience award by a factor derived from GetMemberMap().Length, with a ceiling so that a large party does not outpace players with smaller or no party members.

• Show hints when a second member arrives. In an escape room, activate a hint system when a second party member joins mid-puzzle so that all players see the same hint.

• Keep a cooperative boss fight winnable. Use RemoveMemberEvent to reduce boss health when a party member disconnects so that the remaining players can still win a fight balanced for a larger group.

• Route late joiners to their party. Use AddMemberEvent to send a player who joins mid-session to the spawn point of the party members already on the island.

• Group a results screen by party. On a finishing screen, group each player's party together rather than sorting purely by score so that friends can compare their results.

• Create visual identity.  Run party checks to apply cosmetic VFX to party members for immersion.

What social mechanics does your island reward today, and which of them could read party membership instead of guessing at it?

Continue designing with gameplay tutorials and game mechanic examples. Before you publish, check your island against the Fortnite Developer Rules.