大厅接口

处理大厅的接口

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

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

创建和销毁大厅

EOS_Lobby_CreateLobby 函数可以创建大厅。对函数 EOS_Lobby_CreateLobbyOptions 进行以下初始化:

属性

ApiVersion

EOS_LOBBY_CREATELOBBY_API_LATEST

LocalUserId

创建大厅的用户。该用户将以所有者的身份自动加入大厅。

MaxLobbyMembers

大厅任意时间可容纳的最大用户数

Visibility

大厅是否公开可见(参见权限级别部分了解更多详情)。

操作完成后,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) 按钮、社交叠加和大厅之间的交互,请参见

[社交覆层接入:使用大厅](EpicAccountServices/SocialOverlayIntegration)
。关于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_CopyLobbyDetailsHandleByInviteIdEOS_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(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

大厅因为所有者销毁或者出现错误而关闭。

使用限制

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

[服务使用限制](Overview#ServiceUsageLimitations)

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

功能

服务限制

大厅中的最大玩家数

64

最大会话属性

100

最大成员属性

100

字符串属性长度

1000个字符

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

功能

用户限制

连接

每分钟30次请求

创建大厅

每分钟30次请求

删除大厅

每分钟30次请求

加入大厅

每分钟30次请求

单个用户可同时加入的大厅最大数量

16

读取大厅数据

每分钟100次请求

更新大厅属性

每分钟100次请求

更新成员属性

每分钟100次请求

修改大厅属性

每分钟30次请求

邀请用户

每分钟30次请求

删除邀请

每分钟30次请求

踢出玩家

每分钟30次请求

将成员升级为大厅拥有者

每分钟30次请求

寻找大厅

每分钟30次请求

按ID获取大厅

每分钟100次请求

按用户寻找大厅

每分钟30次请求

按用户寻找邀请

每分钟30次请求

按邀请寻找大厅

每分钟30次请求

单个请求的最大搜索结果

256