大厅接口

此项用于将大厅添加到你的游戏,这样玩家可以创建、加入、离开和管理大厅。

阅读时间19分钟

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

要访问大厅接口,请通过平台接口函数 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如果为true,大厅将与 在线状态 信息关联。一个用户的在线状态一次只能与一个大厅关联。
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(属性- 搜索值) = 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 :大厅的唯一辨识符
  • 大厅所有者 :大厅的当前所有者
  • 大厅成员 :大厅的当前成员
  • 权限级别 :限制谁可以找到或加入大厅;请参见下面的“权限级别”
  • 可用空间 :当前可用的闲置插槽数
  • 最大成员数 :大厅任意时间可容纳的最大用户数
  • 成员数(Member Count) :大厅中的当前成员数量
  • 大厅属性 :与大厅关联的键值对
  • 大厅成员属性 :与每个用户关联的键值对
  • 大厅成员平台 :由服务器识别的单个用户的硬件平台。请注意,该值只为主机平台的大厅成员提供,否则返回一个占位符值。该占位符值表示无法准确识别给定用户的硬件平台。

要查找大厅所有者的ID,请调用 EOS_LobbyDetails_GetLobbyOwner 。要查找大厅成员的ID,请首先调用 EOS_LobbyDetails_GetMemberCount 检索当前成员数,然后遍历当前成员计数,并调用 EOS_LobbyDetails_GetMemberByIndex 。可通过 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这是属性的辨识字符串。搜索属性时,系统会基于此字符串进行比较。
ValueKey 关联的数字、字符串或布尔数据。
ValueType 包含的数据类型。
Visibility通过会话 EOS_ELobbyAttributeVisibility 发布或简单存储在本地的属性。

大厅中的单个用户、或大厅本身最多可以拥有 EOS_LOBBYMODIFICATION_MAX_ATTRIBUTES 项属性。属性名称(Key 中)字段不得超过 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大厅在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房间名称的用例:

  • 注册通知时,例如谈话状态或房间成员身份
  • 将本地用户的房间音频输出禁言或取消禁言时
  • 屏蔽或取消屏蔽房间参与者时
  • 设置本地音频设备设置

大厅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_HardMuteMemberOptions 数据结构调用 EOS_Lobby_HardMuteMember ,强制将某个现有大厅成员禁言。这个结构包含给定成员是否应该被禁言的信息。强制禁言会改变所有人对该大厅成员的语音接受状态,不管他们的本地禁言状态如何。

属性
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