C＃ 和統一的 Amazon GameLift 服務器 SDK 參考：操作 - Amazon GameLift
GetSdkVersion()InitSDK()InitSDK()ProcessReady()ProcessEnding()ActivateGameSession()UpdatePlayerSessionCreationPolicy()GetGameSessionId()GetTerminationTime()AcceptPlayerSession()RemovePlayerSession()DescribePlayerSessions()StartMatchBackfill()StopMatchBackfill()GetComputeCertificate()GetFleetRoleCredentials()摧毀（）

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

C＃ 和統一的 Amazon GameLift 服務器 SDK 參考：操作

這個 Amazon GameLift C# 伺服器開發套件參考可協助您準備好與 Amazon 搭配使用的多人遊戲 GameLift。如需有關整合程序的詳細資訊，請參閱添加 Amazon GameLift 到您的遊戲服務器和如需使用適用於 Unity 的 C# 伺服器 SDK 外掛程式的資訊，請參閱 GameLift 將亞馬遜整合到統一項目中。

GetSdkVersion()

傳回內建至伺服器程序的目前開發套件版本編號。

語法

AwsStringOutcome GetSdkVersion();

傳回值

如果成功，將目前開發套件版本以 AwsStringOutcome 物件傳回。傳回的字串包含版本號碼 (範例5.0.0)。如果不成功，則會傳回錯誤訊息。

範例

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

參數

ServerParameters

若要初始化 Amazon GameLift Anywhere 叢集上的遊戲伺服器，請使用下列資訊建構ServerParameters物件：

  • WebSocket 用來連線到遊戲伺服器的 URL。

  • 用來託管遊戲伺服器的程序 ID。

  • 主控遊戲伺服器處理程序的運算 ID。

  • 包含您的 Amazon GameLift Anywhere 運算的 Amazon GameLift 車隊的 ID。

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

傳回值

如果成功，則返回一個 InitSdkOutcome 對象，以指示服務器進程已準備好調用ProcessReady()。

注意

如果部署到 InitSDK() Anywhere 叢集的遊戲組建時呼叫失敗，請檢查建立組建資源時使用的ServerSdkVersion參數。您必須將此值明確設定為使用中的伺服器 SDK 版本。此參數的預設值為 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()

通 GameLift 知 Amazon 伺服器程序已準備好主持遊戲工作階段。調用後調用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()

通 GameLift 知 Amazon 服務器進程正在終止。在所有其他清理任務（包括關閉活動的遊戲會話）之後以及終止進程之前調用此方法。根據的結果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()

通 GameLift 知 Amazon 伺服器程序已啟動遊戲工作階段，現在已準備好接收玩家連線。在所有遊戲會話初始化之後，應將此操作作為onStartGameSession()回調函數的一部分調用。

語法

GenericOutcome ActivateGameSession()

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例

此範例顯示的是做為 onStartGameSession() 委派函式一部分的 ActivateGameSession() 受到呼叫。

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()

傳回值

如果成功，則會把遊戲工作階段 ID 當成 AwsStringOutcome 物件傳回。如果不成功，則返回錯誤消息。」

範例

AwsStringOutcome getGameSessionIdOutcome = GameLiftServerAPI.GetGameSessionId();

GetTerminationTime()

若設有終止時間，即傳回伺服器程序排定關閉的時間。服務器進程在收到來自 Amazon 的onProcessTerminate()回調後採取此操作 GameLift。Amazon GameLift 呼叫onProcessTerminate()的原因如下：

  • 當服務器進程報告健康狀況不佳或沒有響應 Amazon 時 GameLift。

  • 在縮小事件期間終止執行個體時。

  • 執行個體因為現場執行個體中斷而終止時。

語法

AwsDateTimeOutcome GetTerminationTime()

傳回值

如果成功，則返回終止時間作為AwsDateTimeOutcome對象。該值是終止時間，以之後經過的刻度表示。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()

通 GameLift 知 Amazon 播放器已與服務器進程斷開連接。作為回應，Amazon 將播放器插槽 GameLift 更改為可用。

語法

GenericOutcome RemovePlayerSession(String playerSessionId)

參數

playerSessionId

創建新玩家會話 GameLift 時由 Amazon 發出的唯一 ID。

傳回值

傳回包含錯誤訊息的成功或失敗的一般結果。

範例 

GenericOutcome removePlayerSessionOutcome = GameLiftServerAPI.RemovePlayerSession(playerSessionId);

DescribePlayerSessions()

檢索包括設置，會話元數據和播放器數據的播放器會話數據。使用此動作可取得單一玩家工作階段資訊、一個遊戲工作階段中所有玩家工作階段的資訊，或是與單一玩家 ID 關聯的所有玩家工作階段資訊。

語法

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

參數

DescribePlayerSessionsRequest

描述要擷取哪些玩家工作階段的DescribePlayerSessionsRequest物件。

傳回值

如果成功，會傳回包DescribePlayerSessionsOutcome含一組符合要求參數之播放程式工作階段物件的物件。

範例

此範例展示了讓所有玩家工作階段均主動連線至指定之遊戲工作階段的請求。透過省略限制值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 會使用回調函OnUpdateGameSession()數 GameLift 提供更新的分房系統資料。

一個伺服器程序一次僅能有一個使用中的配對回填請求。若要發送新請求，請先呼叫 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：包含根憑證和中繼憑證的憑證鏈結。

    • rootCertificate.pem：根憑證。

    • privateKey.pem：一般使用者憑證的私密金鑰。

  • ComputeName：計算資源的名稱。

範例

GetComputeCertificateOutcome getComputeCertificateOutcome = GameLiftServerAPI.GetComputeCertificate();

GetFleetRoleCredentials()

擷取 IAM 角色登入資料， GameLift 以授權 Amazon 與其他人互動 AWS 服務。如需詳細資訊，請參閱 與您車隊的其他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);

摧毀（）

從記憶體中釋放 Amazon GameLift 遊戲伺服器 SDK。最佳做法是在終止程序之後ProcessEnding()和之前呼叫此方法。如果您使用的是 Anywhere 叢集，且未在每個遊戲工作階段後終止伺服器程序，請先呼叫Destroy()然InitSDK()後重新初始化，再通知 Amazon GameLift 程序已準備好主持遊戲工作階段。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); 
  }