GetSdkVersion()InitMetrics()InitSDK()InitSDK()ProcessReady()ProcessEnding()ActivateGameSession()UpdatePlayerSessionCreationPolicy()GetGameSessionId()GetTerminationTime()AcceptPlayerSession()RemovePlayerSession()DescribePlayerSessions()StartMatchBackfill()StopMatchBackfill()GetComputeCertificate()GetFleetRoleCredentials()Destroy

适用于 Amazon GameLift Servers 的 C# 服务器 SDK 5.x – 操作

使用服务器 SDK 5.x 参考，将要托管的多人游戏与 Amazon GameLift Servers 集成。有关集成过程的指南，请参阅借助服务器 SDK 将 Amazon GameLift Servers 添加到游戏服务器。如果您使用的是适用于 Unity 的 Amazon GameLift Servers 插件，还可以参阅Amazon GameLift Servers适用于 Unity 的插件（服务器 SDK 5.x）。

适用于 Amazon GameLift Servers 的 C# 服务器 SDK 5.x – 数据类型

主题

GetSdkVersion()
InitMetrics()
InitSDK()
InitSDK()
ProcessReady()
ProcessEnding()
ActivateGameSession()
UpdatePlayerSessionCreationPolicy()
GetGameSessionId()
GetTerminationTime()
AcceptPlayerSession()
RemovePlayerSession()
DescribePlayerSessions()
StartMatchBackfill()
StopMatchBackfill()
GetComputeCertificate()
GetFleetRoleCredentials()
Destroy

GetSdkVersion()

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

语法


AwsStringOutcome GetSdkVersion();

返回值

如果成功，返回以 AwsStringOutcome 对象返回当前 SDK 的版本。返回的字符串仅包含版本号 (例如：如果不成功，将返回错误消息。

示例


var getSdkVersionOutcome = GameLiftServerAPI.GetSdkVersion();

InitMetrics()

初始化指标系统，用于收集和报告服务器性能数据。为了获得最佳结果，请在调用 InitSDK() 之前调用此方法，以便在 SDK 初始化期间启用指标收集。

语法


MetricsManagerOutcome InitMetrics();
MetricsManagerOutcome InitMetrics(MetricsParameters metricsParameters);

参数

MetricsParameters（可选）: 指标收集的配置参数。如果未提供，则使用可以被环境变量覆盖的默认值。

返回值

如果成功，则返回包含该 MetricsManager 实例的MetricsManagerOutcome对象。如果不成功，将返回错误消息。

示例


// Initialize with default parameters (uses environment variables if available)
var outcome = GameLiftServerAPI.InitMetrics();
if (outcome.Success) {
    var metricsManager = outcome.Result;
} else {
    Console.WriteLine("Failed to initialize metrics: " + outcome.Error.ErrorMessage);
}

// Initialize with custom parameters
var metricsParams = new MetricsParameters("localhost", 8125, "crash-host", 9999, 1000, 1024);
var customOutcome = GameLiftServerAPI.InitMetrics(metricsParams);
if (customOutcome.Success) {
    var metricsManager = customOutcome.Result;
}

InitSDK()

为托管 EC2 队列初始化 S Amazon GameLift Servers DK。在与 Amazon GameLift Servers 相关的任何其他初始化发生之前，在启动时调用此方法。此方法从主机环境读取服务器参数，以设置服务器与 Amazon GameLift Servers 服务之间的通信。它使用幂等性令牌，因此当调用失败时，您可以放心地重试此调用。

语法


GenericOutcome InitSDK();

返回值

如果成功，则返回一个 InitSdkOutcome 对象，表示服务器进程已准备好调用ProcessReady()。

示例


//Call InitSDK to establish a local connection with the GameLift agent to enable further communication.
GenericOutcome initSDKOutcome = GameLiftServerAPI.InitSDK();

InitSDK()

为 Anywhere 实例集初始化 Amazon GameLift Servers SDK。在与 Amazon GameLift Servers 相关的任何其他初始化发生之前，在启动时调用此方法。此方法需要明确的服务器参数来设置服务器和 Amazon GameLift Servers 服务之间的通信。它使用幂等性令牌，因此当调用失败时，您可以放心地重试此调用。

语法


GenericOutcome InitSDK(ServerParameters serverParameters);

参数

ServerParameters

要在 Amazon GameLift Servers Anywhere 实例集上初始化游戏服务器，请使用以下信息构造 ServerParameters 对象：

WebSocket 用于连接到您的游戏服务器的 URL。
用于托管游戏服务器的进程的 ID。
托管游戏服务器进程的计算的 ID。
包含您的 Amazon GameLift Servers Anywhere 计算的 Amazon GameLift Servers 实例集的 ID。
Amazon GameLift Servers 操作生成的授权令牌。

返回值

如果成功，则返回一个 InitSdkOutcome 对象，表示服务器进程已准备好调用ProcessReady()。

注意

如果对部署到 InitSDK() Anywhere 队列的游戏版本调用失败，请检查创建编译资源时使用的ServerSdkVersion参数。您必须将此值明确设置为正在使用的服务器软件开发工具包版本。此参数的默认值为 4.x，这不兼容。要解决此问题，请创建新版本并将其部署到新队列。

示例


//Define the server parameters
string websocketUrl = "wss://us-west-1.api.amazongamelift.com";
string processId = "PID1234";
string fleetId = "aarn:aws:gamelift:us-west-1:111122223333:fleet/fleet-9999ffff-88ee-77dd-66cc-5555bbbb44aa";
string hostId = "HardwareAnywhere";
string authToken = "1111aaaa-22bb-33cc-44dd-5555eeee66ff";
ServerParameters serverParameters = 
  new ServerParameters(webSocketUrl, processId, hostId, fleetId, authToken);

//Call InitSDK to establish a local connection with the GameLift agent to enable further communication.
GenericOutcome initSDKOutcome = GameLiftServerAPI.InitSDK(serverParameters);

ProcessReady()

通知 Amazon GameLift Servers，该服务器进程已准备好托管游戏会话。调用后调用InitSDK()此方法。每个进程只能调用一次此方法。

语法


GenericOutcome ProcessReady(ProcessParameters processParameters)

参数

ProcessParameters: ProcessParameters对象保存有关服务器进程的信息。

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例

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


// Set parameters and call ProcessReady
ProcessParameters processParams = new ProcessParameters(
  this.OnStartGameSession,
  this.OnProcessTerminate,
  this.OnHealthCheck,
  this.OnUpdateGameSession,
  port,
  new LogParameters(new List<string>()  
  // Examples of log and error files written by the game server
  {
    "C:\\game\\logs",
    "C:\\game\\error"
  })
);
GenericOutcome processReadyOutcome = GameLiftServerAPI.ProcessReady(processParams);

ProcessEnding()

通知 Amazon GameLift Servers，该服务器进程即将终止。请在已完成所有其他清理任务（包括关闭活动游戏会话）但尚未终止进程时调用此方法。根据的结果ProcessEnding()，进程以成功 (0) 或错误 (-1) 退出并生成队列事件。如果进程因错误而终止，则生成的实例集事件为 SERVER_PROCESS_TERMINATED_UNHEALTHY。

语法


GenericOutcome ProcessEnding()

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例

此示例在使用成功或错误退出代码终止服务器进程Destroy()之前调ProcessEnding()用和。


GenericOutcome processEndingOutcome = GameLiftServerAPI.ProcessEnding();
GameLiftServerAPI.Destroy();

if (processEndingOutcome.Success)
  {
    Environment.Exit(0);
  }
else
  {
    Console.WriteLine("ProcessEnding() failed. Error: " + processEndingOutcome.Error.ToString());
    Environment.Exit(-1);  
  }

ActivateGameSession()

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

语法


GenericOutcome ActivateGameSession()

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例

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


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

UpdatePlayerSessionCreationPolicy()

更新当前游戏会话接受新玩家会话的能力。可将游戏会话设置为接受或拒绝所有新的玩家会话。

语法


GenericOutcome UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy playerSessionPolicy)

参数

playerSessionPolicy

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

有效值包括：

ACCEPT_ALL - 接受所有新玩家会话。
DENY_ALL - 拒绝所有新玩家会话。

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例

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


GenericOutcome updatePlayerSessionPolicyOutcome = 
  GameLiftServerAPI.UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy.ACCEPT_ALL);

GetGameSessionId()

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

对于未通过游戏会话激活的空闲进程，该调用将返回GameLiftError。

语法


AwsStringOutcome GetGameSessionId()

返回值

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

示例


AwsStringOutcome getGameSessionIdOutcome = GameLiftServerAPI.GetGameSessionId();

GetTerminationTime()

如果终止时间可用，则返回安排服务器进程关闭的时间。服务器进程在收到来自 Amazon GameLift Servers 的 onProcessTerminate() 回调后执行此操作。Amazon GameLift Servers 会出于以下原因调用 onProcessTerminate()：

服务器进程报告运行状况不佳或未响应 Amazon GameLift Servers。
在缩减事件期间终止实例时。
当实例因竞价型实例中断而终止时。

语法


AwsDateTimeOutcome GetTerminationTime()

返回值

如果成功，则以AwsDateTimeOutcome对象形式返回终止时间。该值是终止时间，以此后经过的刻度表示。0001 00:00:00例如，日期时间值等2020-09-13 12:26:40 -000Z于637355968000000000刻度。如果没有可用的终止时间，将返回一条错误消息。

示例


AwsDateTimeOutcome getTerminationTimeOutcome = GameLiftServerAPI.GetTerminationTime();

AcceptPlayerSession()

通知 Amazon GameLift Servers，具有所指定玩家会话 ID 的玩家已连接到服务器进程并且需要进行验证。Amazon GameLift Servers 将验证该玩家会话 ID 是否有效。玩家会话经过验证后，Amazon GameLift Servers 会将玩家位置的状态从 RESERVED 更改为 ACTIVE。

语法


GenericOutcome AcceptPlayerSession(String playerSessionId)

参数

playerSessionId: 创建新玩家会话 GameLift 时颁发的唯一 ID。

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例

此示例说明了处理连接请求的函数，包括验证和拒绝无效的玩家会话。 IDs


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

RemovePlayerSession()

通知 Amazon GameLift Servers，有玩家已断开与服务器进程的连接。作为回应，Amazon GameLift Servers 会将玩家位置更改为可用。

语法


GenericOutcome RemovePlayerSession(String playerSessionId)

参数

playerSessionId: 创建新玩家会话时由 Amazon GameLift Servers 颁发的唯一 ID。

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例


GenericOutcome removePlayerSessionOutcome = GameLiftServerAPI.RemovePlayerSession(playerSessionId);

DescribePlayerSessions()

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

语法


DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

参数

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

返回值

如果成功，将返回一个 DescribePlayerSessionsOutcome 对象，包含一组与请求参数相匹配的玩家会话对象。

示例

此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。省略NextToken并将 Limi t 值设置为 10，Amazon GameLift Servers将返回与请求匹配的前 10 个玩家会话记录。


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

StartMatchBackfill()

发送请求以为使用 FlexMatch 创建的游戏会话中的开放位置查找新玩家。有关更多信息，请参阅 FlexMatch 回填功能。

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

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

语法


StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

参数

StartMatchBackfillRequest: StartMatchBackfillRequest对象包含有关回填请求的信息。

返回值

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

示例


// Build a backfill request
StartMatchBackfillRequest startBackfillRequest = new StartMatchBackfillRequest()
{
  TicketId = "1111aaaa-22bb-33cc-44dd-5555eeee66ff", //optional
  MatchmakingConfigurationArn = "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig", 
  GameSessionId = GameLiftServerAPI.GetGameSessionId().Result,    // gets ID for current game session
  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
StartMatchBackfillOutcome 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()

取消活动的对战回填请求。有关更多信息，请参阅 FlexMatch 回填功能。

语法


GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest);

参数

StopMatchBackfillRequest: 一个 StopMatchBackfillRequest 对象，提供有关您要停止的对战票证的详细信息。

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例


// Set backfill stop request parameters
StopMatchBackfillRequest stopBackfillRequest = new StopMatchBackfillRequest(){
  TicketId = "1111aaaa-22bb-33cc-44dd-5555eeee66ff", //optional, if not provided one is autogenerated
  MatchmakingConfigurationArn = "arn:aws:gamelift:us-west-2:111122223333:matchmakingconfiguration/MyMatchmakerConfig",
  GameSessionId = GameLiftServerAPI.GetGameSessionId().Result    //gets the ID for the current game session
};
GenericOutcome stopBackfillOutcome = GameLiftServerAPI.StopMatchBackfillRequest(stopBackfillRequest);

GetComputeCertificate()

检索用于加密游戏服务器和游戏客户端之间网络连接的 TLS 证书的路径。当您将计算设备注册到 Amazon GameLift Servers Anywhere 实例集时，您可以使用该证书路径。有关更多信息，请参阅RegisterCompute。

语法


GetComputeCertificateOutcome GetComputeCertificate();

返回值

返回一个包含以下内容的 GetComputeCertificateResponse 对象：

CertificatePath：计算资源上的 TLS 证书的路径。使用 Amazon GameLift Servers 托管式实例集时，此路径包含：
- certificate.pem：最终用户证书。完整的证书链是certificateChain.pem附加到此证书的组合。
- certificateChain.pem：包含根证书和中间证书的证书链。
- 根证书。
- privateKey.pem：最终用户证书的私钥。
ComputeName：您的计算资源的名称。

示例


GetComputeCertificateOutcome getComputeCertificateOutcome = GameLiftServerAPI.GetComputeCertificate();

GetFleetRoleCredentials()

检索授权 Amazon GameLift Servers 与其他 AWS 服务互动的 IAM 角色凭证。有关更多信息，请参阅将您的Amazon GameLift Servers托管游戏服务器连接到其他 AWS 资源。

语法


GetFleetRoleCredentialsOutcome GetFleetRoleCredentials(GetFleetRoleCredentialsRequest request);

参数

GetFleetRoleCredentialsRequest: 角色证书，用于将有限的 AWS 资源访问权限扩展到游戏服务器。

返回值

返回 GetFleetRoleCredentialsOutcome 对象。

示例


// form the fleet credentials request  
GetFleetRoleCredentialsRequest getFleetRoleCredentialsRequest = new GetFleetRoleCredentialsRequest(){  
  RoleArn = "arn:aws:iam::123456789012:role/service-role/exampleGameLiftAction"  
};
GetFleetRoleCredentialsOutcome GetFleetRoleCredentialsOutcome credentials = GetFleetRoleCredentials(getFleetRoleCredentialsRequest);

Destroy

从内存中释放 Amazon GameLift Servers 游戏服务器 SDK。作为最佳实操，请在终止进程之后ProcessEnding()和之前调用此方法。如果您使用的是 Anywhere 实例集，并且没有在每次游戏会话后终止服务器进程，请先调用 Destroy()，再通过 InitSDK() 重新初始化，最后使用 ProcessReady() 通知 Amazon GameLift Servers 该进程已准备好托管游戏会话。

语法


GenericOutcome Destroy()

返回值

返回由成功或失败组成的通用结果，并显示错误消息。

示例


// Operations to end game sessions and the server process
GenericOutcome processEndingOutcome = GameLiftServerAPI.ProcessEnding();

// Shut down and destroy the instance of the GameLift Game Server SDK
GenericOutcome destroyOutcome = GameLiftServerAPI.Destroy();

// Exit the process with success or failure
if (processEndingOutcome.Success)
  { 
    Environment.Exit(0); 
  }
else
  {
    Console.WriteLine("ProcessEnding() failed. Error: " + processEndingOutcome.Error.ToString());
    Environment.Exit(-1); 
  }

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

数据类型