This API can be used to selectively advertise your multiplayer game session in a Steam chat room group. Tell Steam the number of player spots that are available for your party, and a join-game string, and it will show a beacon in the selected group and allow that many users to “follow” the beacon to your party. Adjust the number of open slots if other players join through alternate matchmaking methods.

For example, you can use ISteamParties in conjunction with a private lobby. Create a private lobby, and then use ISteamParties::CreateBeacon to create a party "beacon" for the number of players desired. The game connect string should indicate the ID of the private lobby.

The beacon will appear in Steam in the specified location (e.g. a Chat Room Group), and also via the in-game ISteamParties API as described below. Steam creates "reservation" slots for the number of desired players. Whenever a user follows the beacon, Steam will hold a reservation slot for them and launch the game using the given connect string.

The game session that created the beacon will be notified of this reservation, so the game can display the appropriate "User <username> is joining your party" or some other indicator. Once the user joins successfully, the game session should call ISteamParties::OnReservationCompleted to tell Steam that the user successfully joined (otherwise, Steam will eventually timeout their reservation and re-open the slot).

When all of the beacon slots are occupied - either by reservations for users still launching the game, or completed slots for users in the party - Steam will hide and disable the beacon.

To cancel the beacon - for instance when the party is full and the game begins - call ISteamParties::DestroyBeacon.

The client side of this operation - seeing and following beacons - can also be managed by your game. Using ISteamParties::GetNumActiveBeacons and ISteamParties::GetBeaconDetails, your game can get a list of beacons from other users that are currently active in locations relevant to the current user. If the user desires, call ISteamParties::JoinParty to "follow" one of those beacons.

Member Functions

Member functions for ISteamParties are called through the global accessor function SteamParties(), which is provided by the header file steam/ISteamMatchmaking.h.

GetNumAvailableBeaconLocations

Name	Type	Description
puNumLocations	uint32*	Address of variable to receive the response number.

Get the number of locations in which you are able to post a party beacon.

Use this to size your result list for a call to ISteamParties::GetAvailableBeaconLocations.

Returns: bool

GetAvailableBeaconLocations

Name	Type	Description
pLocationList	SteamPartyBeaconLocation_t*	Output list of available beacon locations.
uMaxNumLocations	uint32	The maximum number of entries to put into the above list. Should be >= the result from GetNumAvailableBeaconLocations.

Get the list of locations in which you can post a party beacon.

See Also: ISteamParties::GetNumAvailableBeaconLocations

Returns: bool

CreateBeacon

Name	Type	Description
unOpenSlots	uint32	Number of reservation slots to create for the beacon. Normally, this is the size of your desired party minus one (for the current user).
pBeaconLocation	SteamPartyBeaconLocation_t*	Location information for the beacon. Should be one of the locations returned by ISteamParties::GetAvailableBeaconLocations.
pchConnectString	char *	Connect string that will be given to the game on launch for a user that follows the beacon.
pchMetadata	char *	Additional game metadata that can be set on the beacon, and is exposed via ISteamParties::GetBeaconDetails.

Create a beacon. You can only create one beacon at a time. Steam will display the beacon in the specified location, and let up to unOpenSlots users "follow" the beacon to your party.

If users join your party through other matchmaking, adjust the number of remaining open slots using ISteamParties::ChangeNumOpenSlots.

Returns: SteamAPICall_t to be used with a CreateBeaconCallback_t call result.
Returns k_uAPICallInvalid if the process already has an active beacon, or if the location information is invalid.

OnReservationCompleted

Name	Type	Description
ulBeacon	PartyBeaconID_t	Beacon ID for the beacon created by your process.
steamIDUser	CSteamID	SteamID of the user joining your party.

When a user follows your beacon, Steam will reserve one of the open party slots for them, and send your game a ReservationNotificationCallback_t callback. When that user joins your party, call OnReservationCompleted to notify Steam that the user has joined successfully.

ChangeNumOpenSlots

Name	Type	Description
ulBeacon	PartyBeaconID_t	Beacon ID for the beacon created by your process.
unOpenSlots	uint32	The new number of open slots in your party.

If a user joins your party through other matchmaking (perhaps a direct Steam friend, or your own matchmaking system), your game should reduce the number of open slots that Steam is managing through the party beacon. For example, if you created a beacon with five slots, and Steam sent you two ReservationNotificationCallback_t callbacks, and then a third user joined directly, you would want to call ChangeNumOpenSlots with a value of 2 for unOpenSlots. That value represents the total number of new users that you would like Steam to send to your party.

Returns: SteamAPICall_t to be used with a ChangeNumOpenSlotsCallback_t call result.
Returns k_uAPICallInvalid if the beacon ID is invalid.

DestroyBeacon

Name	Type	Description
ulBeacon	PartyBeaconID_t	Beacon ID to be destroyed.

Call this method to destroy the Steam party beacon. This will immediately cause Steam to stop showing the beacon in the target location. Note that any users currently in-flight may still arrive at your party expecting to join.

Your game should call this method when either the party has been filled and the game is beginning, or the user has decided to abandon creating a party. The beacon will be destroyed automatically when your game exits, but the preferred behavior is for the game to call DestroyBeacon at the right time.

Returns: bool

GetNumActiveBeacons

This method has no parameters.

Get the number of active party beacons created by other users for your game, that are visible to the current user.

Returns: uint32

GetBeaconByIndex

Name	Type	Description
unIndex	uint32	Index of Beacon.

Use with ISteamParties::GetNumActiveBeacons to iterate the active beacons visible to the current user. unIndex is a zero-based index, so iterate over the range [0, GetNumActiveBeacons() - 1]. The return is a PartyBeaconID_t that can be used with ISteamParties::GetBeaconDetails to get information about the beacons suitable for display to the user.

Returns: PartyBeaconID_t

GetBeaconDetails

Name	Type	Description
ulBeaconID	PartyBeaconID_t	Beacon ID to query.
pSteamIDBeaconOwner	CSteamID*	Creator of the beacon.
pLocation	SteamPartyBeaconLocation_t*	Location the beacon has been posted.
pchMetadata	char*	Buffer to receive any additional metadata the game has set on this beacon (e.g. game mode). Will be NULL terminated on success
cchMetadata	uint32	Size of the above buffer.

Get details about the specified beacon. You can use the ISteamFriends API to get further details about pSteamIDBeaconOwner, and ISteamParties::GetBeaconLocationData to get further details about pLocation. The pchMetadata contents are specific to your game, and will be whatever was set (if anything) by the game process that created the beacon.

Returns: bool

JoinParty

Name	Type	Description
ulBeacon	PartyBeaconID_t	Beacon ID for the party you wish to join.

When the user indicates they wish to join the party advertised by a given beacon, call this method. On success, Steam will reserve a slot for this user in the party and return the necessary "join game" string to use to complete the connection.

Returns: SteamAPICall_t to be used with a JoinParty_t call result.
Returns k_uAPICallInvalid if the beacon ID is invalid.

GetBeaconLocationData

Name	Type	Description
BeaconLocation	SteamPartyBeaconLocation_t	Location to query.
eData	ESteamPartyBeaconLocationData	Type of location data you wish to get.
pchDataStringOut	char *	Output buffer for location data string. Will be NULL-terminated on success.
cchDataStringOut	int	Size of buffer pointed to by pchDataStringOut.

Query general metadata for the given beacon location. For instance the Name, or the URL for an icon if the location type supports icons (for example, the icon for a Steam Chat Room Group).

Returns: bool

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamParties.

JoinPartyCallback_t

This callback is used as a call response for ISteamParties::JoinParty. On success, you will have reserved a slot in the beacon-owner's party, and should use m_rgchConnectString to connect to their game and complete the process.

Name	Type	Description
m_eResult	EResult	The result of the attempt to join the party.
m_ulBeaconID	PartyBeaconID_t	Beacon ID used in the attempt.
m_SteamIDBeaconOwner	CSteamID	Creator of the beacon used in the attempt.
m_rgchConnectString	char[256]	If successful, a "join game" string for your game to use to complete the process of joining the desired party

CreateBeaconCallback_t

This callback is used as a call response for ISteamParties::CreateBeacon. If successful, your beacon has been posted in the desired location and you may start receiving ISteamParties::ReservationNotificationCallback_t callbacks for users following the beacon.

Name	Type	Description
m_eResult	EResult	The result of the attempt to create a beacon.
m_ulBeaconID	PartyBeaconID_t	Beacon ID of the newly created beacon.

ReservationNotificationCallback_t

After creating a beacon, when a user "follows" that beacon Steam will send you this callback to know that you should be prepared for the user to join your game. When they do join, be sure to call ISteamParties::OnReservationCompleted to let Steam know.

Name	Type	Description
m_ulBeaconID	PartyBeaconID_t	Beacon ID of your beacon.
m_steamIDJoiner	CSteamID	SteamID of the user following your beacon.

ChangeNumOpenSlotsCallback_t

Call result for ISteamParties::ChangeNumOpenSlots.

Name	Type	Description
m_eResult	EResult	The result of the attempt to change the number of open slots.

AvailableBeaconLocationsUpdated_t

Notification that the list of available locations for posting a beacon has been updated.

This callback has no members.

ActiveBeaconsUpdated_t

Notification that the list of active beacons visible to the current user has changed.

This callback has no members.

Structs

These are structs which functions in ISteamParties may return and/or interact with.

SteamPartyBeaconLocation_t

Name	Type	Description
m_eType	ESteamPartyBeaconLocationType	The location type.
m_ulLocationID	uint64	Opaque identifier of this location.

Enums

These are enums which are defined for use with ISteamParties.

ESteamPartyBeaconLocationType

Types of locations where beacons can be posted.

Name	Value	Description
k_ESteamPartyBeaconLocationType_Invalid	0	Invalid location type.
k_ESteamPartyBeaconLocationType_ChatGroup	1	A Steam Chat Room Group.
k_ESteamPartyBeaconLocationType_Max		Value is always one greater than the largest valid location type value.

ESteamPartyBeaconLocationData

Types of extended metadata for beacon locations.

Name	Value	Description
k_ESteamPartyBeaconLocationDataInvalid	0	Invalid location data type.
k_ESteamPartyBeaconLocationDataName	1	The name, if any, of the location
k_ESteamPartyBeaconLocationDataIconURLSmall		If the location has an associated icon, this is the URL for the small format icon image.
k_ESteamPartyBeaconLocationDataIconURLMedium		If the location has an associated icon, this is the URL for the medium format icon image.
k_ESteamPartyBeaconLocationDataIconURLLarge		If the location has an associated icon, this is the URL for the small large icon image.

Typedefs

These are typedefs which are defined for use with ISteamParties.

Name	Base type	Description
PartyBeaconID_t	uint64	A handle to a Steam Party Beacon.