适用于 C# 和 Unity 的亚马逊 GameLift 服务器软件开发工具包参考：操作

此 Amazon GameLift C# 服务器 SDK 参考可帮助您准备多人游戏以供亚马逊使用 GameLift。有关集成过程的详细信息，请参阅将 Amazon GameLift 添加到您的游戏服务器；有关使用适用于 Unity 的 C# 服务器软件开发工具包插件的信息，请参阅将 Amazon GameLift 集成到 Unity 项目中。

GetSdkVersion()

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

语法

AwsStringOutcome GetSdkVersion();

返回值

如果成功，返回以 awsString结果 对象返回当前软件开发工具包的版本。返回的字符串仅包含版本号 (例如：如果不成功，将返回错误消息。

示例

var getSdkVersionOutcome = GameLiftServerAPI.GetSdkVersion();

InitSDK()

为托管 EC2 队列初始化 Amazon GameLift 开发工具包。在启动时调用此方法，然后再进行任何其他与 Amazon GameLift 相关的初始化。此方法从主机环境读取服务器参数，以设置服务器与 Amazon GameLift 服务之间的通信。

语法

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 软件开发工具包。在启动时调用此方法，然后再进行任何其他与 Amazon GameLift 相关的初始化。此方法需要明确的服务器参数来设置服务器和 Amazon GameLift 服务之间的通信。

语法

GenericOutcome InitSDK(ServerParameters serverParameters);

参数

服务器参数

要在 Amazon GameLift Anywhere 舰队上初始化游戏服务器，请使用以下信息构造一个ServerParameters对象：

• WebSocket 用于连接到您的游戏服务器的 URL。

• 用于托管游戏服务器的进程的 ID。

• 托管游戏服务器进程的计算的 ID。

• 包含您的亚马逊 GameLift Anywhere计算的亚马逊 GameLift 舰队的 ID。

• Amazon GameLift 操作生成的授权令牌。

返回值

如果成功，则返回一个 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()

通知 Amaz GameLift on 服务器进程已准备好托管游戏会话。调用后调用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()

通知 Amaz GameLift on 服务器进程即将终止。在完成所有其他清理任务（包括关闭活动游戏会话）之后和终止该进程之前，调用此方法。根据的结果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 服务器进程已激活游戏会话，现在可以接收玩家连接了。此操作应作为 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 (如果服务器进程处于活动状态)。

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

语法

AwsStringOutcome GetGameSessionId()

返回值

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

示例

AwsStringOutcome getGameSessionIdOutcome = GameLiftServerAPI.GetGameSessionId();

GetTerminationTime()

如果终止时间可用，则返回安排服务器进程关闭的时间。服务器进程在收到 Amazon 的onProcessTerminate()回调后采取此操作 GameLift。Amazon GameLift 打电话onProcessTerminate()的原因如下：

• 当服务器进程报告运行状况不佳或没有响应 Amazon 时 GameLift。

• 在缩减事件期间终止实例时。

• 当实例因竞价型实例中断而终止时。

语法

AwsDateTimeOutcome GetTerminationTime()

返回值

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

示例

AwsDateTimeOutcome getTerminationTimeOutcome = GameLiftServerAPI.GetTerminationTime(); 

AcceptPlayerSession()

通知 Amazon GameLift 具有指定玩家会话 ID 的玩家已连接到服务器进程，需要验证。Amazon 会 GameLift 验证玩家会话 ID 是否有效。玩家会话经过验证后，Amazon 会将玩家位置的状态从 “已保留” GameLift 更改为 “活跃”。

语法

GenericOutcome AcceptPlayerSession(String playerSessionId)

参数

playerSessionId

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

返回值

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

示例

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

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 有玩家已断开与服务器进程的连接。作为回应，Amazon将玩家位置 GameLift 更改为可用。

语法

GenericOutcome RemovePlayerSession(String playerSessionId)

参数

playerSessionId

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

返回值

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

示例

GenericOutcome removePlayerSessionOutcome = GameLiftServerAPI.RemovePlayerSession(playerSessionId);

DescribePlayerSessions()

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

语法

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

参数

DescribePlayerSessionsRequest

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

返回值

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

示例

此示例演示了将所有玩家会话主动连接到指定游戏会话的请求。通过省略限制值NextToken并将其设置为 10，Amazon GameLift 将返回与请求匹配的前 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 提供更新的匹配器数据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 Anywhere 队列时，您可以使用证书路径。有关更多信息，请参阅RegisterCompute。

语法

GetComputeCertificateOutcome GetComputeCertificate();

返回值

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

• CertificatePath：计算资源上的 TLS 证书的路径。使用 Amazon GameLift 托管队列时，此路径包含：

  • certificate.pem：最终用户证书。完整的证书链是certificateChain.pem附加到此证书的组合。

  • certificateChain.pem：包含根证书和中间证书的证书链。

  • 根证书。

  • privateKey.pem：最终用户证书的私钥。

• ComputeName：您的计算资源的名称。

示例

GetComputeCertificateOutcome getComputeCertificateOutcome = GameLiftServerAPI.GetComputeCertificate();

GetFleetRoleCredentials()

检索授权 Amazon GameLift 与其他AWS 服务角色互动的 IAM 角色证书。有关更多信息，请参阅与您的实例集中的其他 AWS 资源进行通信。

语法

GetFleetRoleCredentialsOutcome GetFleetRoleCredentials(GetFleetRoleCredentialsRequest request);

参数

获取实例集角色凭证申请

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

返回值

返回 获取实例集角色凭证结果 对象。

示例

// 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 游戏服务器 SDK。作为最佳实操，请在终止进程之后ProcessEnding()和之前调用此方法。如果您使用的是 Anywhere 队列，并且没有在每次游戏会话后终止服务器进程，请先致电Destroy()然后InitSDK()重新初始化，然后再通知 A GameLift mazon 该进程已准备好与之托管游戏会话。ProcessReady()

语法

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); 
  }