GameLift 服务器API(C#)参考: 操作: - Amazon GameLift
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

GameLift 服务器API(C#)参考: 操作:

此 GameLift C# 服务器 API 参考可帮助您准备使用 GameLift 的多人游戏。有关集成过程的详细信息,请参阅 添加 GameLift 到游戏服务器

此 API 在 GameLiftServerAPI.csLogParameters.csProcessParameters.cs 中定义。

AcceptPlayerSession()

通知 GameLift 服务,具有所指定玩家会话 ID 的玩家已连接到服务器进程并且需要验证。GameLift 将确认玩家会话 ID 有效 — 即该玩家 ID 在游戏会话中有保留的玩家位置。通过验证后,GameLift 将玩家位置的状态从 RESERVED 更改为 ACTIVE。

Syntax

GenericOutcome AcceptPlayerSession(String playerSessionId)

Parameters

playerSessionId

当创建了一个新的玩家会话时 GameLift 发出的唯一 ID。玩家会话 ID 在 PlayerSession 对象中指定,作为对 AWS 开发工具包 Amazon GameLift API 操作 StartGameSessionPlacementCreateGameSessionDescribeGameSessionPlacementDescribePlayerSessions 的客户端调用的响应返回。

类型:字符串

必需:否

返回值

返回成功或失败 (包含错误消息) 的一般结果。

Example

此示例演示了处理连接请求的函数,包括验证和拒绝无效的玩家会话 ID。

void ReceiveConnectingPlayerSessionID (Connection connection, String playerSessionId){ var acceptPlayerSessionOutcome = GameLiftServerAPI.AcceptPlayerSession(playerSessionId); if(acceptPlayerSessionOutcome.Success) { connectionToSessionMap.emplace(connection, playerSessionId); connection.Accept(); } else { connection.Reject(acceptPlayerSessionOutcome.Error.ErrorMessage); } }

ActivateGameSession()

通知 GameLift 服务,服务器进程已激活游戏会话,现在已准备好接收玩家连接。此操作应作为 onStartGameSession() 回调函数的一部分,在所有游戏会话初始化已完成之后调用。

Syntax

GenericOutcome ActivateGameSession()

Parameters

此操作没有参数。

返回值

返回成功或失败 (包含错误消息) 的一般结果。

Example

此示例显示了 ActivateGameSession() 作为 onStartGameSession() 委派函数的一部分调用。

void OnStartGameSession(GameSession gameSession) { // game-specific tasks when starting a new game session, such as loading map // When ready to receive players var activateGameSessionOutcome = GameLiftServerAPI.ActivateGameSession(); }

DescribePlayerSessions()

检索玩家会话数据,包括设置、会话元数据和玩家数据。使用此操作获取单个玩家会话的信息、游戏会话中所有玩家会话的信息或者与单个玩家 ID 相关联的所有玩家会话的信息。

Syntax

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

Parameters

describePlayerSessionsRequest

DescribePlayerSessionsRequest 对象描述要检索的玩家会话。

必填 是

返回值

如果成功,将返回一个 DescribePlayerSessionsOutcome 对象,包含一组与请求参数相匹配的玩家会话对象。玩家会话对象与 AWS SDK GameLift API PlayerSession 数据类型具有相同的结构。

Example

此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。通过省略 NextToken 和将 Limit 值设置为 10,GameLift 将返回与请求匹配的前 10 个玩家会话记录。

// Set request parameters var describePlayerSessionsRequest = new Aws.GameLift.Server.Model.DescribePlayerSessionsRequest() { GameSessionId = GameLiftServerAPI.GetGameSessionId().Result, //gets the ID for the current game session Limit = 10, PlayerSessionStatusFilter = PlayerSessionStatusMapper.GetNameForPlayerSessionStatus(PlayerSessionStatus.ACTIVE) }; // Call DescribePlayerSessions Aws::GameLift::DescribePlayerSessionsOutcome playerSessionsOutcome = Aws::GameLift::Server::Model::DescribePlayerSessions(describePlayerSessionRequest);

GetGameSessionId()

检索当前由服务器进程托管的游戏会话的 ID (如果服务器进程处于活动状态)。

Syntax

AwsStringOutcome GetGameSessionId()

Parameters

此操作没有参数。

返回值

如果成功,以 AwsStringOutcome 对象返回游戏会话 ID。如果不成功,将返回错误消息。

Example

var getGameSessionIdOutcome = GameLiftServerAPI.GetGameSessionId();

GetSdkVersion()

返回当前内置到服务器进程中的开发工具包的版本号。

Syntax

AwsStringOutcome GetSdkVersion()

Parameters

此操作没有参数。

返回值

如果成功,返回以 AwsStringOutcome 对象返回当前软件开发工具包的版本。返回的字符串仅包含版本号(例如“3.1.5”)。如果不成功,将返回错误消息。

Example

var getSdkVersionOutcome = GameLiftServerAPI.GetSdkVersion();

GetTerminationTime()

如果终止时间可用,则返回安排服务器进程关闭的时间。服务器进程在收到 onProcessTerminate() 从 GameLift 服务。 GameLift 可能会致电 onProcessTerminate() 原因如下:(1)由于健康状况不佳(服务器进程已报告端口健康状况或尚未响应 GameLift,(2)在缩小事件期间终止实例时,或(3)由于 点实例中断.

如果该进程已收到 onProcessTerminate() 回调,则返回的值是估计的终止时间 (纪元秒)。如果流程未收到 onProcessTerminate() 回叫,则返回一条错误消息。了解有关关闭服务器进程的更多信息。

Syntax

AwsDateTimeOutcome GetTerminationTime()

Parameters

此操作没有参数。

返回值

如果成功,将终止时间返回为 AwsDateTimeOutcome 对象。该值是终止时间(以时期秒为单位)。如果没有可用的终止时间,将返回错误消息。

Example

var getTerminationTimeOutcome = GameLiftServerAPI.GetTerminationTime();

InitSDK()

初始化 GameLift 开发工具包。应在启动之后、进行任何其他 GameLift 相关的初始化之前调用此方法。

Syntax

InitSDKOutcome InitSDK()

Parameters

此操作没有参数。

返回值

如果成功,返回 InitSdkOutcome 对象,指示服务器进程已准备好调用 ProcessReady()

Example

var initSDKOutcome = GameLiftServerAPI.InitSDK();

ProcessEnding()

通知 GameLift 服务,该服务器进程正在关闭。应在所有其他清除任务 (包括关闭所有活动游戏会话) 之后调用此方法。此方法应退出,退出代码为 0;非零退出代码将导致生成一条事件消息,提示进程未完全退出。

Syntax

GenericOutcome ProcessEnding()

Parameters

此操作没有参数。

返回值

返回成功或失败 (包含错误消息) 的一般结果。

Example

var processEndingOutcome = GameLiftServerAPI.ProcessEnding();

ProcessReady()

通知 GameLift 服务,服务器进程已准备好托管游戏会话。成功调用后调用此方法 InitSDK() 和完成服务器进程之前所需的设置任务可以主持游戏会话。此方法每个过程只能调用一次。

Syntax

GenericOutcome ProcessReady(ProcessParameters processParameters)

Parameters

processParameters

ProcessParameters 对象,用于传输有关服务器进程的以下信息:

  • 回调方法的名称,在游戏服务器代码中实现,GameLift 服务调用它来与服务器进程通信。

  • 服务器进程正在侦听的端口号。

  • 您希望 GameLift 捕获和存储的任何游戏会话特定文件的路径。

必填 是

返回值

返回成功或失败 (包含错误消息) 的一般结果。

Example

此示例说明 ProcessReady() 调用和委派函数实施。

// Set parameters and call ProcessReady var processParams = new ProcessParameters( this.OnGameSession, this.OnProcessTerminate, this.OnHealthCheck, this.OnGameSessionUpdate, port, new LogParameters(new List<string>() // Examples of log and error files written by the game server { "C:\\game\\logs", "C:\\game\\error" }) ); var processReadyOutcome = GameLiftServerAPI.ProcessReady(processParams); // Implement callback functions void OnGameSession(GameSession gameSession) { // game-specific tasks when starting a new game session, such as loading map // When ready to receive players var activateGameSessionOutcome = GameLiftServerAPI.ActivateGameSession(); } void OnProcessTerminate() { // game-specific tasks required to gracefully shut down a game session, // such as notifying players, preserving game state data, and other cleanup var ProcessEndingOutcome = GameLiftServerAPI.ProcessEnding(); GameLiftServerAPI.Destroy(); } bool OnHealthCheck() { bool isHealthy; // complete health evaluation within 60 seconds and set health return isHealthy; }

RemovePlayerSession()

通知 GameLift 服务,具有所指定玩家会话 ID 的玩家已从服务器进程断开连接。作为响应,GameLift 将玩家位置更改为可用,这使得该玩家位置可以分配给新玩家。

Syntax

GenericOutcome RemovePlayerSession(String playerSessionId)

Parameters

playerSessionId

当创建了一个新的玩家会话时 GameLift 发出的唯一 ID。玩家会话 ID 在 PlayerSession 对象中指定,作为对 AWS 开发工具包 Amazon GameLift API 操作 StartGameSessionPlacementCreateGameSessionDescribeGameSessionPlacementDescribePlayerSessions 的客户端调用的响应返回。

类型:字符串

必需:否

返回值

返回成功或失败 (包含错误消息) 的一般结果。

示例:

Aws::GameLift::GenericOutcome disconnectOutcome = Aws::GameLift::Server::RemovePlayerSession(playerSessionId);

StartMatchBackfill()

发送请求以为使用 FlexMatch 创建的游戏会话中的开放位置查找新玩家。另请参阅 AWS 软件开发工具包操作 StartMatchBackfill()。通过此操作,托管游戏会话的游戏服务器进程可以发出匹配回填请求。在使用 FlexMatch 回填现有游戏中了解有关 FlexMatch 回填功能的更多信息。

此操作为异步操作。如果成功匹配了新玩家,则 GameLift 服务会使用回调函数 OnUpdateGameSession() 提供更新的对战构建器数据。

服务器进程每次只能具有一个活动的匹配回填请求。要发送新请求,请先调用 StopMatchBackfill() 以取消原始请求。

Syntax

StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

Parameters

StartMatchBackfillRequest

一个 StartMatchBackfillRequest 对象,用于传递以下信息:

  • 要分配给回填请求的票证 ID。此信息是可选的;如果未提供任何 ID,则 GameLift 将自动生成一个 ID。

  • 要将请求发送到的对战构建器。需要完整的配置 ARN。可从游戏会话的对战构建器数据中获得此值。

  • 正在进行回填的游戏会话的 ID。

  • 游戏会话的当前玩家的可用对战数据。

必填 是

返回值

返回带有匹配回填票证 ID 的 StartMatchBackfillOutcome 对象或包含错误消息的失败。

示例:

// Build a backfill request var startBackfillRequest = new AWS.GameLift.Server.Model.StartMatchBackfillRequest() { TicketId = "a ticket ID", //optional MatchmakingConfigurationArn = "the matchmaker configuration ARN", GameSessionId = GameLiftServerAPI.GetGameSessionId().Result, // gets ID for current game session //get player data for all currently connected players MatchmakerData matchmakerData = MatchmakerData.FromJson(gameSession.MatchmakerData); // gets matchmaker data for current players // get matchmakerData.Players // remove data for players who are no longer connected Players = ListOfPlayersRemainingInTheGame }; // Send backfill request var startBackfillOutcome = GameLiftServerAPI.StartMatchBackfill(startBackfillRequest); // Implement callback function for backfill void OnUpdateGameSession(GameSession myGameSession) { // game-specific tasks to prepare for the newly matched players and update matchmaker data as needed }

StopMatchBackfill()

取消使用 StartMatchBackfill() 创建的活动对战回填请求。另请参阅 AWS 软件开发工具包操作 StopMatchmaking()。在使用 FlexMatch 回填现有游戏中了解有关 FlexMatch 回填功能的更多信息。

Syntax

GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest);

Parameters

StopMatchBackfillRequest

一个 StopMatchBackfillRequest 对象,用于识别要取消的对战票证:

  • 分配给被取消的回填请求的票证 ID

  • 回填请求所发送到的对战构建器

  • 与回填请求关联的游戏会话

必填 是

返回值

返回成功或失败 (包含错误消息) 的一般结果。

示例:

// Set backfill stop request parameters var stopBackfillRequest = new AWS.GameLift.Server.Model.StopMatchBackfillRequest() { TicketId = "a ticket ID", //optional, if not provided one is autogenerated MatchmakingConfigurationArn = "the matchmaker configuration ARN", //from the game session matchmaker data GameSessionId = GameLiftServerAPI.GetGameSessionId().Result //gets the ID for the current game session }; var stopBackfillOutcome = GameLiftServerAPI.StopMatchBackfillRequest(stopBackfillRequest);

TerminateGameSession()

此方法已弃用4.0.1版本。相反,服务器进程应调用 ProcessEnding() 游戏间隔结束后。

通知 GameLift 服务器进程已结束当前游戏会话的服务。当服务器进程将保持活动状态并准备好主持新的游戏会话时,此操作称为“。” 只有在您的游戏会话终止程序完成之后才能调用它,因为它向 GameLift 服务器进程可立即用于主持新的游戏会话。

如果在游戏会话停止后服务器进程将关闭,则不调用此操作。相反,请致电 ProcessEnding() 以表明游戏会话和服务器进程都正在结束。

Syntax

GenericOutcome TerminateGameSession()

Parameters

此操作没有参数。

返回值

返回成功或失败 (包含错误消息) 的一般结果。

Example

此示例说明了游戏会话结束时的服务器进程。

// game-specific tasks required to gracefully shut down a game session, // such as notifying players, preserving game state data, and other cleanup var terminateGameSessionOutcome = GameLiftServerAPI.TerminateGameSession(); var processReadyOutcome = GameLiftServerAPI.ProcessReady(processParams);

UpdatePlayerSessionCreationPolicy()

更新当前游戏会话接受新玩家会话的能力。可将游戏会话设置为接受或拒绝所有新的玩家会话。(另请参阅 https://docs.amazonaws.cn/gamelift/latest/apireference/API_UpdateGameSession.html 服务 API 参考 中的 GameLiftUpdateGameSession() 操作)。

Syntax

GenericOutcome UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy playerSessionPolicy)

Parameters

newPlayerSessionPolicy

用于指示游戏会话是否接受新玩家的字符串值。

Type 玩家会话创建策略 枚举。有效值包括:

  • ACCEPT_ALL – 接受所有新玩家会话。

  • DENY_ALL – 拒绝所有新玩家会话。

必填 是

返回值

返回成功或失败 (包含错误消息) 的一般结果。

Example

此示例将当前游戏会话的接入策略设为接受所有玩家。

var updatePlayerSessionCreationPolicyOutcomex = GameLiftServerAPI.UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy.ACCEPT_ALL);