Steamworks 文献库
ISteamParties 接口
此 API 可用于在一个 Steam 聊天室群组中有选择性地宣传您的多人游戏会话。 告知 Steam 您的队伍中可用的玩家空位,以及加入游戏的字符串,选中的群组会显示一个信标,允许相应数量的用户“跟随”此信标前往您的队伍。 如果其他玩家通过不同的匹配方式加入,可调整空位的数量。

例如,您可以将 ISteamParties 与私人房间一起使用。 创建私人房间后,使用 ISteamParties::CreateBeacon 根据您想要的玩家人数创建一个队伍“信标”。 游戏连接字符串应指明私人房间的 ID。

信标将在 Steam 中的指定位置(例如,聊天室组)中显示,并通过如下所述的游戏内 ISteamParties API 出现。 Steam 为所需数量的玩家创建了“预留”位置。 每当用户跟随​​信标时,Steam 都会为他们保留一个预留位置,并使用给定的连接字符串启动该游戏。

创建此信标的游戏会话将收到此预留通知,以便游戏可以显示适当的“用户<username>正在加入您的队伍”或其他一些提示。 用户成功加入后,游戏会话必须调用 ISteamParties::OnReservationCompleted 告知 Steam 用户已成功加入(否则,Steam 最终将使其预留超时并重新打开此空位)。

当所有信标空位都填满时(要么是为仍在启动游戏的用户预留空位,要么是队伍中的用户占满了空位),Steam 将隐藏并禁用信标,

要取消信标(例如在队伍已满且游戏开始时),请调用 ISteamParties::DestroyBeacon

查看和跟随信标的客户端操作也可以在您的游戏中管理。 使用 ISteamParties::GetNumActiveBeaconsISteamParties::GetBeaconDetails,游戏可以从在与当前用户关联的位置上处于活跃状态的其他用户处获取信标列表。 如果用户需要,请调用 ISteamParties::JoinParty 以“跟随”这些信标中的任何一个。

成员函数

ISteamParties 的成员函数通过全局访问器函数 SteamParties() 调用,该函数由头文件
steam/ISteamMatchmaking.h 提供。

GetNumAvailableBeaconLocations

bool GetNumAvailableBeaconLocations( uint32 *puNumLocations );
名称类型描述
puNumLocationsuint32*接收响应编号的变量的地址。

获取可以在其中发布队伍信标的位置的数量。

使用此函数可确定调用 ISteamParties::GetAvailableBeaconLocations 的结果列表的大小。

返回: bool

GetAvailableBeaconLocations

bool GetAvailableBeaconLocations( SteamPartyBeaconLocation_t *pLocationList, uint32 uMaxNumLocations );
名称类型描述
pLocationListSteamPartyBeaconLocation_t*可用信标位置的输出列表。
uMaxNumLocationsuint32要放入上面列表中的最大条目数。 必须大于或等于 GetNumAvailableBeaconLocations 的结果。

获取可以在其中发布队伍信标的位置列表。

另见: ISteamParties::GetNumAvailableBeaconLocations

返回: bool

CreateBeacon

SteamAPICall_t CreateBeacon( uint32 unOpenSlots, SteamPartyBeaconLocation_t *pBeaconLocation, const char *pchConnectString, const char *pchMetadata );
名称类型描述
unOpenSlotsuint32为信标创建的预留空位数。 通常,这是所需的队伍人数减去1(对当前的用户来说)。
pBeaconLocationSteamPartyBeaconLocation_t*信标的位置信息。 必须是 ISteamParties::GetAvailableBeaconLocations 返回的位置之一。
pchConnectStringchar *跟随信标的用户的游戏在启动时将会获得的链接字符串。
pchMetadatachar *可以在信标上设置并通过 ISteamParties::GetBeaconDetails 公开其他游戏元数据。

创建一个信标。 一次只能创建一个信标。 Steam 将在指定的位置显示信标,并让最多 unOpenSlots 名用户“跟随”此信标前往你的队伍。

如果用户通过其他匹配加入您的队伍,请使用 ISteamParties::ChangeNumOpenSlots 调整剩余的空位数量。

返回: SteamAPICall_t,与 CreateBeaconCallback_t 调用结果一起使用。
如果进程已具有使用中的信标,或者位置信息无效,则返回 k_uAPICallInvalid

OnReservationCompleted

void OnReservationCompleted( PartyBeaconID_t ulBeacon, CSteamID steamIDUser );
名称类型描述
ulBeaconPartyBeaconID_t由您的进程创建的信标的信标 ID。
steamIDUserCSteamID加入您队伍的用户的 SteamID。

当用户跟随​​您的信标时,Steam 会为他们预留一个开放的队伍空位,并向您的游戏发送ReservationNotificationCallback_t 回调。 当该用户加入您的队伍时,请调用 OnReservationCompleted 以通知 Steam 该用户已成功加入。

ChangeNumOpenSlots

SteamAPICall_t ChangeNumOpenSlots( PartyBeaconID_t ulBeacon, uint32 unOpenSlots );
名称类型描述
ulBeaconPartyBeaconID_t由您的进程创建的信标的信标 ID。
unOpenSlotsuint32您队伍中新的空位数量。

如果用户通过其他匹配(也许直接通过 Steam 上的好友或您自己的匹配系统)加入您的队伍,则游戏应减少 Steam 通过队伍信标管理的开放空位数量。 例如,如果您创建了一个有五个空位的信标,且 Steam 向您发送了两个 ReservationNotificationCallback_t 回调,然后第三个用户直接加入,那么您可能需要为 unOpenSlots 调用值为 2 的 ChangeNumOpenSlots。 该值是您希望 Steam 发送给您队伍的 用户总数。

返回: SteamAPICall_t,与 ChangeNumOpenSlotsCallback_t 调用结果一起使用。
如果信标 ID 无效,则返回 k_uAPICallInvalid

DestroyBeacon

bool DestroyBeacon( PartyBeaconID_t ulBeacon );
名称类型描述
ulBeaconPartyBeaconID_t信标 ID 将被删除。

调用此方法将删除 Steam 队伍信标。 这将导致 Steam 立即停止在目标位置显示信标。 请注意,当前尚未加入的用户可能仍在等待加入该队伍。

当队伍已满且游戏开始时,或用户决定放弃创建队伍时,则游戏应调用此方法。 该信标将在游戏结束时自动销毁,但是如果游戏在正确的时间调用 DestroyBeacon 则更可取。

返回: bool

GetNumActiveBeacons

uint32 GetNumActiveBeacons();

此方法没有参数。

获取由 其他 用户为您游戏创建并对当前用户可见的使用中的队伍信标数量。

返回: uint32

GetBeaconByIndex

PartyBeaconID_t GetBeaconByIndex( uint32 unIndex );
名称类型描述
unIndex uint32信标索引。

ISteamParties::GetNumActiveBeacons 一起使用,以对当前用户可见的激活信标进行迭代。 unIndex是从 0 开始的索引,因此需要在 [0, GetNumActiveBeacons() - 1] 范围内进行循环访问。 返回值为 PartyBeaconID_t,可与 ISteamParties::GetBeaconDetails 一起使用,以获取可向用户显示的信标的相关信息。

返回: PartyBeaconID_t

GetBeaconDetails

bool GetBeaconDetails( PartyBeaconID_t ulBeaconID, CSteamID *pSteamIDBeaconOwner,SteamPartyBeaconLocation_t *pLocation, char *pchMetadata, int cchMetadata );
名称类型描述
ulBeaconIDPartyBeaconID_t要查询的信标 ID。
pSteamIDBeaconOwnerCSteamID*信标的创建者。
pLocationSteamPartyBeaconLocation_t*信标的位置已发布。
pchMetadatachar*用于接收游戏给此信标设置的任何其他元数据(例如,游戏模式)的缓冲区。 成功时将以 NULL 结尾。
cchMetadata uint32以上缓冲区的大小。

获取指定信标的详细信息。 您可以使用 ISteamFriends API 来获取 pSteamIDBeaconOwner 的更多详细信息,并用 ISteamParties::GetBeaconLocationData 来获取 pLocation 的更多详细信息。 pchMetadata 内容特定于您的游戏,将是创建信标的游戏过程所设置的任意值(如果存在的话)。

返回: bool

JoinParty

SteamAPICall_t JoinParty( PartyBeaconID_t ulBeaconID );
名称类型描述
ulBeaconPartyBeaconID_t您要加入的队伍的信标 ID 。

当用户指明他们希望加入通过给定信标而了解到的群时,请调用此方法。 成功后,Steam 将为此用户在队伍中预留一个空位,并返回所需的“加入游戏”字符串完成连接。

返回: SteamAPICall_t,与 JoinParty_t 调用结果一起使用。
如果信标 ID 无效,则返回 k_uAPICallInvalid

GetBeaconLocationData

bool GetBeaconLocationData( SteamPartyBeaconLocation_t BeaconLocation, ESteamPartyBeaconLocationData eData, char *pchDataStringOut, int cchDataStringOut );
名称类型描述
BeaconLocationSteamPartyBeaconLocation_t 要查询的位置。
eDataESteamPartyBeaconLocationData 您希望获取的位置数据的类型。
pchDataStringOutchar *位置数据字符串的输出缓冲区。 成功时将以 NULL 结尾。
cchDataStringOut int缓冲区的大小,由 pchDataStringOut 指定。

查询给定信标位置的常规元数据。 例如,查询名称,或者在位置类型支持图标的情况下查询图标的 URL(比如 Steam 聊天室群组的图标)。

返回: bool

回调

以下是可以通过调用 SteamAPI_RunCallbacks 触发的回调。 其中许多将响应 ISteamParties 的成员函数直接触发。

JoinPartyCallback_t

此回调用作对 ISteamParties::JoinParty 的调用响应。 成功后,您将在信标所有者的队伍中保留一个空位,并应使用 m_rgchConnectString 连接到他们的游戏并完成此流程。

名称类型描述
m_eResultEResult尝试加入队伍的结果。
m_ulBeaconIDPartyBeaconID_t尝试时使用的信标 ID。
m_SteamIDBeaconOwnerCSteamID尝试时使用的信标的创建者。
m_rgchConnectStringchar[256]如果成功,则游戏可以使用“加入游戏”字符串来完成加入所需队伍的过程。

CreateBeaconCallback_t

此回调用作对 ISteamParties::CreateBeacon 的调用响应。 如果成功,则信标已经发布到您希望的位置,并且您将开始为跟随信标的用户接收 ISteamParties::ReservationNotificationCallback_t 回调。

名称类型描述
m_eResultEResult尝试创建信标的结果。
m_ulBeaconIDPartyBeaconID_t新创建信标的信标 ID。

ReservationNotificationCallback_t

在创建信标之后,当用户“跟随”此信标时,Steam 将发送此回调以告知您应为用户加入游戏做好准备。 当他们加入后,请确保调用 ISteamParties::OnReservationCompleted 让 Steam 知晓。

名称类型描述
m_ulBeaconIDPartyBeaconID_t您信标的信标 ID。
m_steamIDJoinerCSteamID跟随您信标的用户的 SteamID。

ChangeNumOpenSlotsCallback_t

调用 ISteamParties::ChangeNumOpenSlots 的结果。

名称类型描述
m_eResultEResult试图更改开放空位数的结果。

AvailableBeaconLocationsUpdated_t

关于发布信标的可用位置列表已更新的通知。

该回调无成员。

ActiveBeaconsUpdated_t

关于当前用户可见的使用中信标列表已更改的通知

该回调无成员。

结构

以下是 ISteamParties 中的函数可能返回和/或与之交互的结构。

SteamPartyBeaconLocation_t



名称类型描述
m_eTypeESteamPartyBeaconLocationType位置类型。
m_ulLocationIDuint64此位置的不透明标识符。

枚举

以下是经过定义来与 ISteamParties 一起使用的枚举。

ESteamPartyBeaconLocationType

可以发布信标的位置类型。

名称描述
k_ESteamPartyBeaconLocationType_Invalid0无效的位置类型。
k_ESteamPartyBeaconLocationType_ChatGroup1Steam 聊天室群组。
k_ESteamPartyBeaconLocationType_Max该值始终为有效位置类型的最大值 +1。

ESteamPartyBeaconLocationData

信标位置的扩展元数据类型。

名称描述
k_ESteamPartyBeaconLocationDataInvalid0无效的位置数据类型。
k_ESteamPartyBeaconLocationDataName1位置名称(如果有)
k_ESteamPartyBeaconLocationDataIconURLSmall如果该位置有相关联的图标,则这是小尺寸图标图片的 URL。
k_ESteamPartyBeaconLocationDataIconURLMedium如果该位置有相关联的图标,则这是中等尺寸图标图片的 URL。
k_ESteamPartyBeaconLocationDataIconURLLarge如果该位置有相关联的图标,则这是大尺寸图标图片的 URL。

Typedefs

以下是经过定义来与 ISteamFriends 一起使用的 typedefs。

名称基类型描述
PartyBeaconID_tuint64Steam 队伍信标的句柄。