Lobbies Interface

处理大厅的接口

阅读时间17分钟

大厅提供用户之间持久连接,通过实时更新共享游戏和用户状态。通常情况下,用户可以创建或加入大厅,与其他用户组队、选择游戏开始前的选项,并等待其他玩家加入后一起游戏。借助 大厅接口,用户可以创建、加入、离开和管理大厅。

要访问大厅接口,请通过平台接口函数 EOS_Platform_GetLobbyInterface 获取 EOS_HLobby 句柄。所有大厅接口函数都需要以此句柄作为其第一个参数。EOS_HPlatform 柄必须tick,以便在操作完成时触发相应的回调。

创建和销毁大厅

EOS_Lobby_CreateLobby 函数可以创建大厅。更多的属性详情,请参见EOS_Lobby_CreateLobbyOptions。 对函数 EOS_Lobby_CreateLobbyOptions 进行以下初始化:

属性
ApiVersionEOS_LOBBY_CREATELOBBY_API_LATEST
LocalUserId创建大厅的用户。该用户将以所有者的身份自动加入大厅。
MaxLobbyMembers大厅任意时间可容纳的最大用户数
PermissionLevel大厅是否公开可见(参见权限级别部分了解更多详情)。
BucketId大厅的Bucket ID。
bPresenceEnabled如果为真,大厅将与状态信息关联。一个用户的状态只能与一个大厅关联。
bAllowInvites大厅成员是否允许邀请其他人。
bDisableHostMigration是否允许主机迁移/如果原主机离开,大厅是否会继续开放。
bEnableRTCRoom为大厅所有成员创建一个实时通讯(RTC)房间。大厅的所有成员在连接到大厅时将自动加入RTC房间,当他们离开或从大厅移除时,他们将自动离开RTC房间。虽然RTC房间的加入和离开是自动的,但应用程序仍然需要使用EOS RTC接口来处理房间的所有其他功能。

操作完成后,EOS_Lobby_OnCreateLobbyCallback 将以 EOS_Lobby_CreateLobbyCallbackInfo 数据结构运行。如果数据结构的 ResultCode 字段显示成功,则 LobbyId 字段将包含新大厅的ID值,与大厅进一步交互时需要用到此值。

要销毁大厅,大厅的所有者必须以 EOS_Lobby_DestroyLobbyOptions 结构调用 EOS_Lobby_DestroyLobby,此结构的初始化信息如下:

属性
ApiVersionEOS_LOBBY_DESTROYLOBBY_API_LATEST
LocalUserId要求销毁大厅的用户;该用户当前必须是大厅的所有者。
LobbyId要销毁大厅的ID。

完成后,EOS_Lobby_OnDestroyLobbyCallback 回调函数将以 EOS_Lobby_DestroyLobbyCallbackInfo 数据结构运行。该数据结构指示销毁是否成功。大厅关闭后,其将自动删除所有剩余成员,并触发状态为 EOS_LMS_CLOSED 的成员状态更新。

大厅生命周期

大厅的生命周期通常遵循此顺序:

  • 用户创建大厅。该用户自动加入大厅并成为首位成员兼所有者。
  • 所有者设置大厅的初始状态,并且可以邀请用户加入。
  • 其他用户加入和离开大厅。连接后,成员可以更新自己的状态信息,并且可以邀请其他用户。
  • 大厅主人可以根据游戏状态更新具体数据。
  • 所有者可以将成员移出大厅,也可以将所有者身份转移给其他成员。
  • 用户可以在不离开或销毁大厅的情况下进行多轮游戏。你的游戏逻辑决定了一个大厅的生命时长。
  • 最后,所有者销毁大厅。

加入或离开大厅

使用有效的 EOS_HLobbyDetails 柄调用 EOS_Lobby_JoinLobby,会使用户尝试加入该柄引用的大厅。一个用户可以同时处于多个大厅中;用户加入一个大厅时无需离开另一个大厅。加入一个新的大厅不会离开任何现有的大厅。离开或销毁一个大厅必须是显式的。

要离开大厅,请调用 EOS_Lobby_LeaveLobby。如果要离开的用户是当前的大厅所有者,EOS将从其余用户中选择新的所有者。若有用户离开,以及所有权发生变更,所有成员都会收到通知。

邀请用户进入大厅

大厅中的用户可以利用 EOS_Lobby_SendInvite 函数邀请其他用户加入。成功发送邀请后,将触发类型为 EOS_Lobby_OnSendInviteCallback 的回调。邀请到达时,目标用户将收到[通知]。然后,游戏使用 EOS_Lobby_AddNotifyLobbyInviteAccepted 来了解玩家何时点击覆层中的 接受(Accept)。关于 邀请(Invite) 按钮、社交叠加和大厅之间的交互,请参见社交覆层接入:使用大厅。关于Epic Games启动程序的邀请功能,请确保将你的部署映射到你的构件

拒绝邀请

要拒绝邀请,请以 EOS_Lobby_RejectInviteOptions 结构调用 EOS_Lobby_RejectInvite,其中包含以下信息:

属性
ApiVersionEOS_LOBBY_REJECTINVITE_API_LATEST
LobbyId与邀请关联的大厅ID
LocalUserId拒绝邀请的用户ID

完成后,EOS_Lobby_OnRejectInviteCallback 函数将以 EOS_Lobby_RejectInviteCallbackInfo 数据结构在本地触发。如果成功,邀请将从系统中永久删除。

更新全部邀请

若要保证本地缓存中包含所有待处理邀请,请以 EOS_Lobby_QueryInvitesOptions 结构调用 EOS_Lobby_QueryInvites。此结构包含以下数据:

属性
ApiVersionEOS_LOBBY_QUERYINVITES_API_LATEST
LocalUserId要获取其邀请的用户ID

操作完成后,你的 EOS_Lobby_OnQueryInvitesCallback 将以 EOS_Lobby_QueryInvitesCallbackInfo 数据结构运行。成功时,本地缓存将包含指定用户的所有待处理邀请,你可以搜索这类邀请。若要在启动时发现用户离线期间发送的所有邀请,此函数将十分实用。在游戏期间,凭借注册通知,用户几乎不需要调用此函数。

从缓存获取邀请

要检查已缓存的邀请,首先以 EOS_Lobby_GetInviteCountOptions 结构调用 EOS_Lobby_GetInviteCount,初始化如下:

属性
ApiVersionEOS_LOBBY_GETINVITECOUNT_API_LATEST
LocalUserId要计入其邀请的本地用户

此函数针对本地缓存运行,并立即返回一个 uint32_t,指出缓存中待处理邀请的数量。然后,可以以 EOS_Lobby_GetInviteIdByIndexOptions 结构调用 EOS_Lobby_GetInviteIdByIndex,此结构包含以下数据:

属性
ApiVersionEOS_LOBBY_GETINVITEIDBYINDEX_API_LATEST
LocalUserId拥有邀请的本地用户
Index要获取的邀请索引

EOS_Lobby_GetInviteIdByIndex 也会针对本地缓存运行,如果调用成功,将立即返回 EOS_Success。成功后,你提供的输出参数将包含邀请数据的副本及其大小。不再需要缓冲时,需要由你进行清理。

通知

只要用户已通过 EOS_Lobby_AddNotifyLobbyInviteReceived 注册回调,用户就会收到实时邀请。回调数据包含邀请的所有相关信息。此时,用户可以使用 EOS_Lobby_CopyLobbyDetailsHandleByInviteIdEOS_HLobbyDetails 形式获取邀请,用户必须拥有它才能加入大厅。关闭应用程序或离线时,使用 EOS_Lobby_RemoveNotifyLobbyInviteReceived 从通知列表中删除回调。

从大厅中移除成员

大厅拥有者可以随时移除大厅成员。为此,以 EOS_Lobby_KickMemberOptions 数据结构调用 EOS_Lobby_KickMember,初始化如下:

属性
ApiVersionEOS_LOBBY_KICKMEMBER_API_LATEST
LobbyId要移除成员的大厅ID。
LocalUserId请求移除的大厅成员ID。这必须是大厅所有者。
EOS_ProductUserId TargetUserId将要移除的大厅成员ID。

操作完成后,将收到 EOS_Lobby_OnKickMemberCallback 函数调用,数据结构为 EOS_Lobby_KickMemberCallbackInfo。此外,所有剩余的大厅成员将收到 EOS_LMSC_KICKED 事件的通知。

搜索大厅

EOS_Lobby_CreateLobbySearch 可创建柄(类型为 EOS_HLobbySearch),可用于搜索设为可发现的大厅(详情请参见“权限级别”)。使用下面的函数配置此柄,然后调用 EOS_LobbySearch_Find 执行。成功完成后,应用程序可以浏览搜索结果。多项搜索操作可以使用不同的柄同时运行。

搜索完成后,使用 EOS_LobbySearch_GetSearchResultCount 获取给定 EOS_HLobbySearch 柄的结果数。然后可以使用 EOS_LobbySearch_CopySearchResultByIndex 来请求个体结果的副本。数据副本使用完后,使用 EOS_LobbyDetails_Release 将其处理掉,以回收使用的内存。

按大厅ID搜索

如果用户知道准确的大厅ID,则可以使用 EOS_LobbySearch_SetLobbyId 直接搜索。与其他用户共享大厅ID会超出API的范围。

按用户ID搜索

EOS_LobbySearch_SetTargetUserId 可获取已知用户ID,并返回代表目标用户所属大厅的搜索结果。

按属性搜索

要查找大厅,最可靠的方法是搜索所需的设置子集。这可用于响应在用户接口中选择了一组过滤器的用户,可以基于用户的技能和其他因素在场景幕后自动完成,或者结合两种方法来完成。

EOS_LobbySearch_SetParameter 允许用户设置 EOS_Lobby_AttributeData,并提供 EOS_EComparisonOp,指示如何将该属性与服务中存储的所有现有大厅进行比较。一个或多个此类调用将设置搜索参数,搜索参数之间存在隐式布尔值 AND

比较运算符

运算符说明
适用于所有属性类型的比较
EOS_CO_EQUAL搜索值为属性。
EOS_CO_NOTEQUAL搜索值并非属性。
适用于数字类型的比较
EOS_CO_GREATERTHAN属性大于搜索值。
EOS_CO_GREATERTHANOREQUAL属性大于或等于搜索值。
EOS_CO_LESSTHAN属性小于搜索值。
EOS_CO_LESSTHANOREQUAL属性小于或等于搜索值。
EOS_CO_DISTANCE属性接近搜索值,遵循公式 abs(attribute - searchvalue) = 0
适用于字符串类型的比较
EOS_CO_ANYOF该属性是用分号分隔的字符串值列表中的任意一项。例如:“This;OrThis;MaybeThis”
EOS_CO_NOTANYOF该属性不属于字符串值列表中的任意一项。例如:“NotThis;OrThisEither”

限制搜索结果

要限制可获取的最大搜索结果数,请使用 EOS_LobbySearch_SetMaxResults 函数。

获取有关大厅的信息

要了解大厅,用户可以请求 EOS_HLobbyDetails 柄。基于本地用户与大厅的连接,有三个函数可提供此信息:

  • EOS_Lobby_CopyLobbyDetailsHandle 可供当前连接到大厅的用户使用。
  • EOS_Lobby_CopyLobbyDetailsHandleByInviteId 需要大厅邀请。
  • EOS_LobbySearch_CopySearchResultByIndex 适用于本地用户在搜索中找到的大厅。

成功完成上述任意操作之后将收到一个 EOS_HLobbyDetails 柄,该柄可用于访问以下信息:

  • 大厅ID:大厅的唯一辨识符
  • 大厅所有者:大厅的当前所有者
  • 权限级别:限制谁可以找到或加入大厅;请参见下面的“权限级别”
  • 可用空间:当前可用的闲置插槽数
  • 最大成员数:大厅任意时间可容纳的最大用户数
  • 大厅属性:与大厅关联的键值对
  • 大厅成员属性:与每个用户关联的键值对
  • 大厅成员平台:由服务器识别的用户的硬件平台。请注意,该值只为主机平台的大厅成员提供,否则返回一个占位符值。该占位符值表示无法准确识别给定用户的硬件平台。

要查找大厅所有者的ID,请调用 EOS_LobbyDetails_GetLobbyOwner。可通过 EOS_LobbyDetails_CopyInfo 函数以 EOS_LobbyDetails_Info 数据结构形式获取有关大厅的细节。你接收的 EOS_LobbyDetails_Info 将是EOS SDK缓存信息的副本。你拥有此数据,必须使用 EOS_LobbyDetails_Info_Release 函数将其释放,以避免内存泄漏。数据是快照,如果有关大厅的信息在收到后发生更改,数据将不会更新。

权限级别

大厅的权限级别负责控制用户发现并加入大厅的条件。所有者可以随时调用 EOS_LobbyModification_SetPermissionLevel 更改权限级别。以下设置可用:

权限级别(宏)大厅行为
EOS_LPL_PUBLICADVERTISED这是公共大厅;只要大厅未满,任何用户都可以随时找到或使用此大厅。
EOS_LPL_JOINVIAPRESENCE这个大厅仅对朋友开放;大厅不会在公共搜索中显示,只有所有者的朋友可以加入。不过,这个大厅并不是私有的;只要知道大厅ID就能找到它。
EOS_LPL_INVITEONLY这是私人大厅,不会出现搜索中。用户只能通过已在大厅中的用户发送的邀请才能加入大厅。

修改大厅或用户信息

用户可以修改大厅,成员也可以修改自身的用户数据,方法是调用 EOS_Lobby_UpdateLobbyModification 以获取大厅修改句柄(类型为 EOS_HLobbyModification)。

变更所有权

所有者可以调用 EOS_Lobby_PromoteMember,将大厅的另一位成员升级为所有者。大厅只能设一位所有者,因此调用者将在此过程中丧失所有者身份。所有成员都会收到此事件的通知。

大厅和大厅成员属性

大厅和各个用户可以拥有应用程序专属的键值属性,该属性由 EOS_Lobby_Attribute 数据类型提供支持。这些属性必须用数字、字符串或布尔数据表示即可。EOS_Lobby_Attribute 数据结构包含此信息。

字段内容
Key这是属性的辨识字符串。搜索属性时,系统会基于此字符串进行比较。
Value 关联的数字、字符串或布尔数据。
ValueType 包含的数据类型。
Visibility通过会话 EOS_ELobbyAttributeVisibility 发布或简单存储在本地的属性。

大厅中的单个用户、或大厅本身最多可以拥有 EOS_LOBBYMODIFICATION_MAX_ATTRIBUTES 项属性。属性名称( 中)字段不得超过 EOS_LOBBYMODIFICATION_MAX_ATTRIBUTE_LENGTH 个字符。

当前的大厅所有者可以通过以下函数更改大厅:

函数效果
EOS_LobbyModification_SetPermissionLevel使用此函数可设置大厅的权限级别。
EOS_LobbyModification_SetMaxMembers此函数可更改大厅中能够同时存在的最大用户数。该值的可接受范围处于当前大厅中的用户数与 EOS_LOBBY_MAX_LOBBY_MEMBERS 之间。
EOS_LobbyModification_AddAttribute此函数可将新键值对添加到大厅数据中。
EOS_LobbyModification_RemoveAttribute此函数可将键值对从大厅数据中删除。

已连接的用户可以使用以下函数修改自己的数据:

函数效果
EOS_LobbyModification_AddMemberAttribute将新键值对添加到大厅的特定成员。
EOS_LobbyModification_RemoveMemberAttribute删除大厅特定成员的键值对。

完成全部所需属性修改后,必须将这些更改提交到大厅,修改才会生效。调用 EOS_Lobby_UpdateLobby 完成此操作。操作结束后,修改完成,其他大厅成员将收到通知。你还将收到对回调函数的调用。

事件通知

用户与大厅保持持久连接,并且会收到大厅生命周期内所发生事件的通知。注册通知可以在启动时完成,每次回调都会提供足够的信息,完整描述受影响的大厅。

大厅数据更新

大厅所有者更改大厅属性时,所有大厅成员都会收到通知。通知仅简单说明已发生变更。游戏应计算大厅中的所有可用数据,然后将其重新应用于游戏。

用户数据更新

大厅成员更改大厅属性时,所有大厅成员都会收到通知。通知仅简单说明已发生变更。游戏应计算大厅中的所有可用数据,然后将其重新应用于游戏。

大厅成员属性

当用户在大厅进行下列活动时,系统会向大厅内的所有其他用户发出通知:

事件类型含义
EOS_LMS_JOINED新用户已加入大厅;预计不久之后会有大厅成员更新。
EOS_LMS_LEFT现有用户已离开大厅,其专属数据已删除。
EOS_LMS_DISCONNECTED现有用户意外离开大厅。
EOS_LMS_KICKED大厅所有者已从大厅删除特定用户。
EOS_LSM_PROMOTED现有用户已由前所有者显式升级,或当大厅所有者离开大厅时隐式升级。
EOS_LMS_CLOSED大厅因为所有者销毁或者出现错误而关闭。

语音通讯

借助EOS大厅(EOS Lobby),你可以在Epic服务器或你自己的后台服务器上创建语音聊天室。用户可以在多个平台上的比赛或游戏大厅中实现一对一或多人语音聊天。详情请参见大厅语音语音接口

维持连接

使用EOS大厅RTC房间功能的应用无需考虑手动加入或离开语音室。这会由大厅系统自动处理。如果成功创建了大厅并启用了RTC房间,只要本地用户还在大厅里,大厅系统就会自动加入并保持与RTC房间的连接。

应用程序可以使用 EOS_Lobby_IsRTCRoomConnectedEOS_Lobby_AddNotifyRTCRoomConnectionChangedEOS_Lobby_RemoveNotifyRTCRoomConnectionChanged 来获得所需信息。例如,在多人游戏大厅中与大厅RTC服务断开连接时,显示断开图标。

与RTC功能互动

如需与 EOS_RTC_* 或 EOS_RTCAudio_* 系列函数交互,应用程序必须首先使用 EOS_Lobby_GetRTCRoomName 函数来获得与大厅相关的房间名称。EOS_Lobby_GetRTCRoomName 最早可以在 EOS_Lobby_OnJoinLobbyCallbackEOS_Lobby_OnCreateLobbyCallback 中调用,此时结果参数为 EOS_Success。此时,应用应该注册所有的RTC通知,以免错过可能的通知,例如房间的现有成员(可能在这些通知后不久发生)。

RTC房间名称的用例:

  • 注册通话状态的通知
  • 对本地用户的音频输出进行静音(或取消静音)
  • 屏蔽(或解除屏蔽)房间的加入者
  • 设置本地音频设备

大厅RTC替换函数

以下函数可以替换常用的 EOS_RTC_* 函数,但不兼容大厅,原因是该功能会内部处理,或者应用不再提供数据,或者该功能基于 EOS_RTCAdmin_* 函数。

函数作用
EOS_Lobby_GetRTCRoomName获取本地用户所在大厅的关联RTC房间的名称。
EOS_Lobby_IsRTCRoomConnected获取大厅RTC房间的当前连接状态。
EOS_Lobby_AddNotifyRTCRoomConnectionChanged注册函数,用于在大厅RTC房间发生连接状态变化时接受通知。通知的回调信息包括通知关联的RTC房间和本地用户。
EOS_Lobby_RemoveNotifyRTCRoomConnectionChanged取消注册函数,不再接受RTC房间连接状态改变时的通知。
EOS_Lobby_HardMuteMember允许大厅主人对房间内的某些大厅成员进行静音或取消静音。

强制静音

作为大厅所有者,你可以通过调用 EOS_Lobby_HardMuteMemberEOS_Lobby_HardMuteMemberOptions 数据结构来强制静音某个现有大厅成员。这个结构包含给定成员是否应该被静音的信息。强制静音会改变所有人对该大厅成员的语音接受状态,不管他们的本地静音状态如何。

属性
ApiVersionEOS_LOBBY_HARDMUTEMEMBER_API_LATEST
LobbyId大厅的ID。
LocalUserId请求强制静音的用户。用户必须是大厅主人。
TargetUserId将被强制(取消强制)静音的用户。
bHardMute用户的强制静音状态(开启或关闭)。

操作完成后,你的 EOS_Lobby_OnHardMuteMemberCallback 会运行一个 EOS_Lobby_HardMuteMemberCallbackInfo 数据结构。如果数据结构的 ResultCode 字段显示执行成功,它的 LobbyId 字段将显示大厅的ID值,TargetUserId 包含强制静音状态更新过的成员。

使用限制

聊天室为用户提供了持久连接,旨在通过实时更新来共享游戏和用户状态。通常,用户可以创建或加入大厅来与其他用户聊天,组建队伍,在游戏开始前设置选项,一起等待其他用户加入。有关节流、使用配额和最佳实践的信息,请参阅服务使用限制

以下是大厅服务的一般限制:

功能服务限制
大厅中的最大玩家数64
最大会话属性100
最大成员属性100
字符串属性长度1000个字符

此外,还存在根据每个用户情况而定的速率限制。请阅读以下限制,以免遭到节流:

功能用户限制
连接每分钟30次请求
创建大厅每分钟30次请求
删除大厅每分钟30次请求
加入大厅每分钟30次请求
单个用户可同时加入的大厅最大数量16
读取大厅数据每分钟100次请求
更新大厅属性每分钟100次请求
更新成员属性每分钟100次请求
修改大厅属性每分钟30次请求
邀请用户每分钟30次请求
删除邀请每分钟30次请求
踢出玩家每分钟30次请求
将成员升级为大厅拥有者每分钟30次请求
寻找大厅每分钟30次请求
按ID获取大厅每分钟100次请求
按用户寻找大厅每分钟30次请求
按用户寻找邀请每分钟30次请求
按邀请寻找大厅每分钟30次请求
单个请求的最大搜索结果256