大厅提供用户之间持久连接,通过实时更新共享游戏和用户状态。通常情况下,用户可以创建或加入大厅,与其他用户组队、选择游戏开始前的选项,并等待其他玩家加入后一起游戏。借助 大厅接口 ,用户可以创建、加入、离开和管理大厅。
要访问大厅接口,请通过平台接口函数 EOS_Platform_GetLobbyInterface
获取 EOS_HLobby
句柄。所有大厅接口函数都需要以此句柄作为其第一个参数。 EOS_HPlatform
句柄必须tick,以便在操作完成时触发相应的回调。
创建和销毁大厅
EOS_Lobby_CreateLobby
函数可以创建大厅。如需更多的属性详情,请参阅EOS_Lobby_CreateLobbyOptions。对函数 EOS_Lobby_CreateLobbyOptions
进行以下初始化:
属性 | 值 |
---|---|
ApiVersion | EOS_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
,此结构的初始化信息如下:
属性 | 值 |
---|---|
ApiVersion | EOS_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
,其中包含以下信息:
属性 | 值 |
---|---|
ApiVersion | EOS_LOBBY_REJECTINVITE_API_LATEST |
LobbyId | 与邀请关联的大厅ID |
LocalUserId | 拒绝邀请的用户ID |
完成后,EOS_Lobby_OnRejectInviteCallback
函数将以 EOS_Lobby_RejectInviteCallbackInfo
数据结构在本地触发。如果成功,邀请将从系统中永久删除。
更新全部邀请
若要保证本地缓存中包含所有待处理邀请,请以 EOS_Lobby_QueryInvitesOptions
结构调用 EOS_Lobby_QueryInvites
。此结构包含以下数据:
属性 | 值 |
---|---|
ApiVersion | EOS_LOBBY_QUERYINVITES_API_LATEST |
LocalUserId | 要检索其邀请的用户ID |
操作完成后,你的 EOS_Lobby_OnQueryInvitesCallback
将以 EOS_Lobby_QueryInvitesCallbackInfo
数据结构运行。成功时,本地缓存将包含指定用户的所有待处理邀请,你可以搜索这类邀请。若要在启动时发现用户离线期间发送的所有邀请,此函数将十分实用。在游戏期间,凭借注册通知,用户几乎不需要调用此函数。
检索缓存中的邀请
要检查已缓存的邀请,首先以 EOS_Lobby_GetInviteCountOptions
结构调用 EOS_Lobby_GetInviteCount
,初始化如下:
属性 | 值 |
---|---|
ApiVersion | EOS_LOBBY_GETINVITECOUNT_API_LATEST |
LocalUserId | 要计入其邀请的本地用户 |
此函数针对本地缓存运行,并立即返回一个 uint32_t
,指出缓存中待处理邀请的数量。然后,可以以 EOS_Lobby_GetInviteIdByIndexOptions
结构调用 EOS_Lobby_GetInviteIdByIndex
,此结构包含以下数据:
属性 | 值 |
---|---|
ApiVersion | EOS_LOBBY_GETINVITEIDBYINDEX_API_LATEST |
LocalUserId | 拥有邀请的本地用户 |
Index | 要检索的邀请索引 |
EOS_Lobby_GetInviteIdByIndex
也会针对本地缓存运行,如果调用成功,将立即返回 EOS_Success
。成功后,你提供的输出参数将包含邀请数据的副本及其大小。不再需要缓冲时,需要由你进行清理。
通知
只要用户已通过 EOS_Lobby_AddNotifyLobbyInviteReceived
注册回调,用户就会收到实时邀请。回调数据包含邀请的所有相关信息。此时,用户可以使用 EOS_Lobby_CopyLobbyDetailsHandleByInviteId
以 EOS_HLobbyDetails
形式获取邀请,用户必须拥有它才能加入大厅。关闭应用程序或离线时,使用 EOS_Lobby_RemoveNotifyLobbyInviteReceived
从通知列表中删除回调。
从大厅中移除成员
大厅拥有者可以随时移除大厅成员。为此,以 EOS_Lobby_KickMemberOptions
数据结构调用 EOS_Lobby_KickMember
,初始化如下:
属性 | 值 |
---|---|
ApiVersion | EOS_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
函数将其释放,以避免内存泄漏。数据是快照,如果有关大厅的信息在收到后发生更改,数据将不会更新。
注意 :你不能将上述API调用用于大厅搜索结果。
权限级别
大厅的权限级别负责控制用户发现并加入大厅的条件。所有者可以随时调用 EOS_LobbyModification_SetPermissionLevel
更改权限级别。以下设置可用:
权限级别(宏) | 大厅行为 |
---|---|
EOS_LPL_PUBLICADVERTISED | 这是公共大厅;只要大厅未满,任何用户都可以随时找到或使用此大厅。 |
EOS_LPL_JOINVIAPRESENCE | 这个大厅仅对朋友开放;大厅不会在公共搜索中显示,只有所有者的朋友可以加入。不过,这个大厅并非私有;知道大厅ID就能找到它。 |
EOS_LPL_INVITEONLY | 这是私人大厅,不会出现搜索中。用户只能通过已在大厅中的用户发送的邀请才能加入大厅。 |
修改大厅或用户信息
用户可以修改大厅,成员也可以修改自身的用户数据,方法是调用 EOS_Lobby_UpdateLobbyModification
以获取大厅修改句柄(类型为 EOS_HLobbyModification
)。
变更所有权
所有者可以调用 EOS_Lobby_PromoteMember
,将大厅的另一位成员升级为所有者。大厅只能设一位所有者,因此调用者将在此过程中丧失所有者身份。所有成员都会收到此事件的通知。
大厅和大厅成员属性
注意 :在 EOS SDK 1.16 版本中,如果使用 EOS_LobbyModification_AddAttribute
向大厅添加属性,但未修改大厅所有者成员属性,那么,之前使用 EOS_LobbyModification_AddMemberAttribute
设置的大厅所有者成员属性将被删除。请参阅版本说明:已知问题和应对措施了解更多信息。
大厅和各个用户可以拥有应用程序专属的键值属性,该属性由 EOS_Lobby_Attribute
数据类型提供支持。这些属性必须用数字、字符串或布尔数据表示。 EOS_Lobby_Attribute
数据结构包含此信息。
大厅和大厅成员属性有公共和私有可视性。在公共可视性下,数据针对大厅属性对大厅外部的所有成员可见,并且数据针对大厅成员属性在大厅内可见。反过来,对于私有可视性,数据针对大厅属性在大厅内部可见,并且数据针对大厅成员属性仅对该成员可见。
字段 | 内容 |
---|---|
Key | 这是属性的辨识字符串。搜索属性时,系统会基于此字符串进行比较。 |
Value | 与 Key 关联的数字、字符串或布尔数据。 |
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_IsRTCRoomConnected
、 EOS_Lobby_AddNotifyRTCRoomConnectionChanged
和 EOS_Lobby_RemoveNotifyRTCRoomConnectionChanged
来获得所需信息。例如,在多人游戏大厅中与大厅RTC服务断开连接时,显示断开图标。
与RTC功能互动
如需与 EOS_RTC_
* 或 EOS_RTCAudio_
* 系列函数交互,应用程序必须首先使用 EOS_Lobby_GetRTCRoomName
函数来获得与大厅相关的房间名称。 EOS_Lobby_GetRTCRoomName
最早可以在 EOS_Lobby_OnJoinLobbyCallback
或 EOS_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
,强制将某个现有大厅成员禁言。这个结构包含给定成员是否应该被禁言的信息。强制禁言会改变所有人对该大厅成员的语音接受状态,不管他们的本地禁言状态如何。
属性 | 值 |
---|---|
ApiVersion | EOS_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 |