เอกสาร Steamworks
ISteamParties Interface
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

bool GetNumAvailableBeaconLocations( uint32 *puNumLocations );
NameTypeDescription
puNumLocationsuint32*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

bool GetAvailableBeaconLocations( SteamPartyBeaconLocation_t *pLocationList, uint32 uMaxNumLocations );
NameTypeDescription
pLocationListSteamPartyBeaconLocation_t*Output list of available beacon locations.
uMaxNumLocationsuint32The 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

SteamAPICall_t CreateBeacon( uint32 unOpenSlots, SteamPartyBeaconLocation_t *pBeaconLocation, const char *pchConnectString, const char *pchMetadata );
NameTypeDescription
unOpenSlotsuint32Number of reservation slots to create for the beacon. Normally, this is the size of your desired party minus one (for the current user).
pBeaconLocationSteamPartyBeaconLocation_t*Location information for the beacon. Should be one of the locations returned by ISteamParties::GetAvailableBeaconLocations.
pchConnectStringchar *Connect string that will be given to the game on launch for a user that follows the beacon.
pchMetadatachar *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

void OnReservationCompleted( PartyBeaconID_t ulBeacon, CSteamID steamIDUser );
NameTypeDescription
ulBeaconPartyBeaconID_tBeacon ID for the beacon created by your process.
steamIDUserCSteamIDSteamID 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

SteamAPICall_t ChangeNumOpenSlots( PartyBeaconID_t ulBeacon, uint32 unOpenSlots );
NameTypeDescription
ulBeaconPartyBeaconID_tBeacon ID for the beacon created by your process.
unOpenSlotsuint32The 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

bool DestroyBeacon( PartyBeaconID_t ulBeacon );
NameTypeDescription
ulBeaconPartyBeaconID_tBeacon 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

uint32 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

PartyBeaconID_t GetBeaconByIndex( uint32 unIndex );
NameTypeDescription
unIndex uint32Index 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

bool GetBeaconDetails( PartyBeaconID_t ulBeaconID, CSteamID *pSteamIDBeaconOwner,SteamPartyBeaconLocation_t *pLocation, char *pchMetadata, int cchMetadata );
NameTypeDescription
ulBeaconIDPartyBeaconID_tBeacon ID to query.
pSteamIDBeaconOwnerCSteamID*Creator of the beacon.
pLocationSteamPartyBeaconLocation_t*Location the beacon has been posted.
pchMetadatachar*Buffer to receive any additional metadata the game has set on this beacon (e.g. game mode). Will be NULL terminated on success
cchMetadata uint32Size 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

SteamAPICall_t JoinParty( PartyBeaconID_t ulBeaconID );
NameTypeDescription
ulBeaconPartyBeaconID_tBeacon 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

bool GetBeaconLocationData( SteamPartyBeaconLocation_t BeaconLocation, ESteamPartyBeaconLocationData eData, char *pchDataStringOut, int cchDataStringOut );
NameTypeDescription
BeaconLocationSteamPartyBeaconLocation_t Location to query.
eDataESteamPartyBeaconLocationData Type of location data you wish to get.
pchDataStringOutchar *Output buffer for location data string. Will be NULL-terminated on success.
cchDataStringOut intSize 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.

NameTypeDescription
m_eResultEResultThe result of the attempt to join the party.
m_ulBeaconIDPartyBeaconID_tBeacon ID used in the attempt.
m_SteamIDBeaconOwnerCSteamIDCreator of the beacon used in the attempt.
m_rgchConnectStringchar[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.

NameTypeDescription
m_eResultEResultThe result of the attempt to create a beacon.
m_ulBeaconIDPartyBeaconID_tBeacon 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.

NameTypeDescription
m_ulBeaconIDPartyBeaconID_tBeacon ID of your beacon.
m_steamIDJoinerCSteamIDSteamID of the user following your beacon.

ChangeNumOpenSlotsCallback_t

Call result for ISteamParties::ChangeNumOpenSlots.

NameTypeDescription
m_eResultEResultThe 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



NameTypeDescription
m_eTypeESteamPartyBeaconLocationTypeThe location type.
m_ulLocationIDuint64Opaque identifier of this location.

Enums

These are enums which are defined for use with ISteamParties.

ESteamPartyBeaconLocationType

Types of locations where beacons can be posted.

NameValueDescription
k_ESteamPartyBeaconLocationType_Invalid0Invalid location type.
k_ESteamPartyBeaconLocationType_ChatGroup1A Steam Chat Room Group.
k_ESteamPartyBeaconLocationType_MaxValue is always one greater than the largest valid location type value.

ESteamPartyBeaconLocationData

Types of extended metadata for beacon locations.

NameValueDescription
k_ESteamPartyBeaconLocationDataInvalid0Invalid location data type.
k_ESteamPartyBeaconLocationDataName1The name, if any, of the location
k_ESteamPartyBeaconLocationDataIconURLSmallIf the location has an associated icon, this is the URL for the small format icon image.
k_ESteamPartyBeaconLocationDataIconURLMediumIf the location has an associated icon, this is the URL for the medium format icon image.
k_ESteamPartyBeaconLocationDataIconURLLargeIf 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.

NameBase typeDescription
PartyBeaconID_tuint64A handle to a Steam Party Beacon.