此 API 可用于在一个 Steam 聊天室群组中有选择性地宣传您的多人游戏会话。 告知 Steam 您的队伍中可用的玩家空位,以及加入游戏的字符串,选中的群组会显示一个信标,允许相应数量的用户“跟随”此信标前往您的队伍。 如果其他玩家通过不同的匹配方式加入,可调整空位的数量。
例如,您可以将 ISteamParties 与私人房间一起使用。 创建私人房间后,使用
ISteamParties::CreateBeacon 根据您想要的玩家人数创建一个队伍“信标”。 游戏连接字符串应指明私人房间的 ID。
信标将在 Steam 中的指定位置(例如,聊天室组)中显示,并通过如下所述的游戏内 ISteamParties API 出现。 Steam 为所需数量的玩家创建了“预留”位置。 每当用户跟随信标时,Steam 都会为他们保留一个预留位置,并使用给定的连接字符串启动该游戏。
创建此信标的游戏会话将收到此预留通知,以便游戏可以显示适当的“用户<username>正在加入您的队伍”或其他一些提示。 用户成功加入后,游戏会话必须调用
ISteamParties::OnReservationCompleted 告知 Steam 用户已成功加入(否则,Steam 最终将使其预留超时并重新打开此空位)。
当所有信标空位都填满时(要么是为仍在启动游戏的用户预留空位,要么是队伍中的用户占满了空位),Steam 将隐藏并禁用信标,
要取消信标(例如在队伍已满且游戏开始时),请调用
ISteamParties::DestroyBeacon。
查看和跟随信标的客户端操作也可以在您的游戏中管理。 使用
ISteamParties::GetNumActiveBeacons 和
ISteamParties::GetBeaconDetails,游戏可以从在与当前用户关联的位置上处于活跃状态的其他用户处获取信标列表。 如果用户需要,请调用
ISteamParties::JoinParty 以“跟随”这些信标中的任何一个。
成员函数
ISteamParties
的成员函数通过全局访问器函数
SteamParties()
调用,该函数由头文件
steam/ISteamMatchmaking.h
提供。
GetNumAvailableBeaconLocations
bool GetNumAvailableBeaconLocations( uint32 *puNumLocations );
名称 | 类型 | 描述 |
puNumLocations | uint32* | 接收响应编号的变量的地址。 |
获取可以在其中发布队伍信标的位置的数量。
使用此函数可确定调用
ISteamParties::GetAvailableBeaconLocations 的结果列表的大小。
返回: bool
GetAvailableBeaconLocations
bool GetAvailableBeaconLocations( SteamPartyBeaconLocation_t *pLocationList, uint32 uMaxNumLocations );
获取可以在其中发布队伍信标的位置列表。
另见: ISteamParties::GetNumAvailableBeaconLocations返回: bool
CreateBeacon
SteamAPICall_t CreateBeacon( uint32 unOpenSlots, SteamPartyBeaconLocation_t *pBeaconLocation, const char *pchConnectString, const char *pchMetadata );
创建一个信标。 一次只能创建一个信标。 Steam 将在指定的位置显示信标,并让最多 unOpenSlots 名用户“跟随”此信标前往你的队伍。
如果用户通过其他匹配加入您的队伍,请使用
ISteamParties::ChangeNumOpenSlots 调整剩余的空位数量。
返回: SteamAPICall_t,与
CreateBeaconCallback_t 调用结果一起使用。
如果进程已具有使用中的信标,或者位置信息无效,则返回
k_uAPICallInvalid。
OnReservationCompleted
void OnReservationCompleted( PartyBeaconID_t ulBeacon, CSteamID steamIDUser );
当用户跟随您的信标时,Steam 会为他们预留一个开放的队伍空位,并向您的游戏发送
ReservationNotificationCallback_t 回调。 当该用户加入您的队伍时,请调用
OnReservationCompleted 以通知 Steam 该用户已成功加入。
ChangeNumOpenSlots
SteamAPICall_t ChangeNumOpenSlots( PartyBeaconID_t ulBeacon, uint32 unOpenSlots );
如果用户通过其他匹配(也许直接通过 Steam 上的好友或您自己的匹配系统)加入您的队伍,则游戏应减少 Steam 通过队伍信标管理的开放空位数量。 例如,如果您创建了一个有五个空位的信标,且 Steam 向您发送了两个
ReservationNotificationCallback_t 回调,然后第三个用户直接加入,那么您可能需要为 unOpenSlots 调用值为 2 的
ChangeNumOpenSlots。 该值是您希望 Steam 发送给您队伍的
新用户总数。
返回: SteamAPICall_t,与
ChangeNumOpenSlotsCallback_t 调用结果一起使用。
如果信标 ID 无效,则返回
k_uAPICallInvalid。
DestroyBeacon
bool DestroyBeacon( PartyBeaconID_t ulBeacon );
调用此方法将删除 Steam 队伍信标。 这将导致 Steam 立即停止在目标位置显示信标。 请注意,当前尚未加入的用户可能仍在等待加入该队伍。
当队伍已满且游戏开始时,或用户决定放弃创建队伍时,则游戏应调用此方法。 该信标将在游戏结束时自动销毁,但是如果游戏在正确的时间调用
DestroyBeacon 则更可取。
返回: bool
GetNumActiveBeacons
uint32 GetNumActiveBeacons();
此方法没有参数。
获取由
其他 用户为您游戏创建并对当前用户可见的使用中的队伍信标数量。
返回: uint32
GetBeaconByIndex
PartyBeaconID_t GetBeaconByIndex( uint32 unIndex );
与
ISteamParties::GetNumActiveBeacons 一起使用,以对当前用户可见的激活信标进行迭代。
unIndex是从 0 开始的索引,因此需要在 [0, GetNumActiveBeacons() - 1] 范围内进行循环访问。 返回值为
PartyBeaconID_t,可与
ISteamParties::GetBeaconDetails 一起使用,以获取可向用户显示的信标的相关信息。
返回: PartyBeaconID_tGetBeaconDetails
bool GetBeaconDetails( PartyBeaconID_t ulBeaconID, CSteamID *pSteamIDBeaconOwner,SteamPartyBeaconLocation_t *pLocation, char *pchMetadata, int cchMetadata );
获取指定信标的详细信息。 您可以使用
ISteamFriends API 来获取
pSteamIDBeaconOwner 的更多详细信息,并用
ISteamParties::GetBeaconLocationData 来获取
pLocation 的更多详细信息。
pchMetadata 内容特定于您的游戏,将是创建信标的游戏过程所设置的任意值(如果存在的话)。
返回: bool
JoinParty
SteamAPICall_t JoinParty( PartyBeaconID_t ulBeaconID );
当用户指明他们希望加入通过给定信标而了解到的群时,请调用此方法。 成功后,Steam 将为此用户在队伍中预留一个空位,并返回所需的“加入游戏”字符串完成连接。
返回: SteamAPICall_t,与
JoinParty_t 调用结果一起使用。
如果信标 ID 无效,则返回
k_uAPICallInvalid。
GetBeaconLocationData
bool GetBeaconLocationData( SteamPartyBeaconLocation_t BeaconLocation, ESteamPartyBeaconLocationData eData, char *pchDataStringOut, int cchDataStringOut );
查询给定信标位置的常规元数据。 例如,查询名称,或者在位置类型支持图标的情况下查询图标的 URL(比如 Steam 聊天室群组的图标)。
返回: bool
回调
以下是可以通过调用
SteamAPI_RunCallbacks 触发的回调。 其中许多将响应
ISteamParties
的成员函数直接触发。
JoinPartyCallback_t
此回调用作对
ISteamParties::JoinParty 的调用响应。 成功后,您将在信标所有者的队伍中保留一个空位,并应使用
m_rgchConnectString 连接到他们的游戏并完成此流程。
名称 | 类型 | 描述 |
m_eResult | EResult | 尝试加入队伍的结果。 |
m_ulBeaconID | PartyBeaconID_t | 尝试时使用的信标 ID。 |
m_SteamIDBeaconOwner | CSteamID | 尝试时使用的信标的创建者。 |
m_rgchConnectString | char[256] | 如果成功,则游戏可以使用“加入游戏”字符串来完成加入所需队伍的过程。 |
CreateBeaconCallback_t
此回调用作对
ISteamParties::CreateBeacon 的调用响应。 如果成功,则信标已经发布到您希望的位置,并且您将开始为跟随信标的用户接收
ISteamParties::ReservationNotificationCallback_t 回调。
ReservationNotificationCallback_t
在创建信标之后,当用户“跟随”此信标时,Steam 将发送此回调以告知您应为用户加入游戏做好准备。 当他们加入后,请确保调用
ISteamParties::OnReservationCompleted 让 Steam 知晓。
ChangeNumOpenSlotsCallback_t
调用
ISteamParties::ChangeNumOpenSlots 的结果。
名称 | 类型 | 描述 |
m_eResult | EResult | 试图更改开放空位数的结果。 |
AvailableBeaconLocationsUpdated_t
关于发布信标的可用位置列表已更新的通知。
该回调无成员。
ActiveBeaconsUpdated_t
关于当前用户可见的使用中信标列表已更改的通知
该回调无成员。
结构
以下是 ISteamParties 中的函数可能返回和/或与之交互的结构。
SteamPartyBeaconLocation_t
枚举
以下是经过定义来与 ISteamParties 一起使用的枚举。
ESteamPartyBeaconLocationType
可以发布信标的位置类型。
名称 | 值 | 描述 |
k_ESteamPartyBeaconLocationType_Invalid | 0 | 无效的位置类型。 |
k_ESteamPartyBeaconLocationType_ChatGroup | 1 | Steam 聊天室群组。 |
k_ESteamPartyBeaconLocationType_Max | | 该值始终为有效位置类型的最大值 +1。 |
ESteamPartyBeaconLocationData
信标位置的扩展元数据类型。
名称 | 值 | 描述 |
k_ESteamPartyBeaconLocationDataInvalid | 0 | 无效的位置数据类型。 |
k_ESteamPartyBeaconLocationDataName | 1 | 位置名称(如果有) |
k_ESteamPartyBeaconLocationDataIconURLSmall | | 如果该位置有相关联的图标,则这是小尺寸图标图片的 URL。 |
k_ESteamPartyBeaconLocationDataIconURLMedium | | 如果该位置有相关联的图标,则这是中等尺寸图标图片的 URL。 |
k_ESteamPartyBeaconLocationDataIconURLLarge | | 如果该位置有相关联的图标,则这是大尺寸图标图片的 URL。 |
Typedefs
以下是经过定义来与 ISteamFriends 一起使用的 typedefs。
名称 | 基类型 | 描述 |
PartyBeaconID_t | uint64 | Steam 队伍信标的句柄。 |