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

Amazon GameLift Server SDK 4.x for C#：動作

使用 Amazon GameLift C# 伺服器SDK參考，整合您的多人遊戲以與 Amazon 託管 GameLift。如需整合程序的指引，請參閱 將 Amazon GameLift 新增至您的遊戲伺服器。

Amazon GameLift Server SDK 4.x for C#：資料類型

AcceptPlayerSession()

通知 Amazon GameLift 服務，具有指定播放器工作階段 ID 的播放器已連線至伺服器程序，且需要驗證。Amazon 會 GameLift 驗證播放器工作階段 ID 是否有效，也就是說，播放器 ID 已在遊戲工作階段中保留播放器插槽。驗證後，Amazon 會將播放器插槽的狀態從 GameLift 變更為 RESERVED ACTIVE。

語法

GenericOutcome AcceptPlayerSession(String playerSessionId)

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

此範例說明處理連線請求的函數，包括驗證和拒絕無效的播放器工作階段 IDs。

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

通知 Amazon GameLift 服務伺服器程序已啟用遊戲工作階段，現在已準備好接收玩家連線。此動作應當做 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   
    var activateGameSessionOutcome = GameLiftServerAPI.ActivateGameSession();
}

DescribePlayerSessions()

擷取玩家工作階段資料，包括設定、工作階段中繼資料和玩家資料。使用此動作可取得單一玩家工作階段資訊、一個遊戲工作階段中所有玩家工作階段的資訊，或是與單一玩家 ID 關聯的所有玩家工作階段資訊。

語法

DescribePlayerSessionsOutcome DescribePlayerSessions(DescribePlayerSessionsRequest describePlayerSessionsRequest)

參數

傳回值

如果成功，會傳回 DescribePlayerSessionsOutcome 物件，內含一組與請求參數相符的玩家工作階段物件。播放器工作階段物件的結構與 AWS SDK Amazon GameLift API PlayerSession資料類型相同。

範例

此範例展示了讓所有玩家工作階段均主動連線至指定之遊戲工作階段的請求。透過省略限制值NextToken並將其設定為 10，Amazon 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。

對於尚未透過遊戲工作階段啟用的閒置程序，呼叫會傳回 Success=True 和 GameSessionId="" （空字串）。

語法

AwsStringOutcome GetGameSessionId()

參數

此動作沒有參數。

傳回值

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

範例

var getGameSessionIdOutcome = GameLiftServerAPI.GetGameSessionId();

GetInstanceCertificate()

擷取與機群及其執行個體相關聯的 pem 編碼TLS憑證的檔案位置。當您建立憑證組態設為 的新機群時 AWS Certificate Manager ， 會產生此憑證GENERATED。使用此憑證可與遊戲用戶端建立安全連線，以及加密用戶端/伺服器通訊。

語法

GetInstanceCertificateOutcome GetInstanceCertificate();

參數

此動作沒有參數。

傳回值

如果成功， 會傳回GetInstanceCertificateOutcome物件，其中包含存放在執行個體上的機群TLS憑證檔案和憑證鏈的位置。從憑證鏈擷取的根憑證檔案也會儲存在執行個體上。如果不成功，則會傳回錯誤訊息。

如需憑證和憑證鏈資料的詳細資訊，請參閱 參考中的 AWS Certificate Manager APIGetCertificate 回應元素。

範例

var getInstanceCertificateOutcome = GameLiftServerAPI.GetInstanceCertificate();

GetSdkVersion()

傳回伺服器程序中SDK內建 的目前版本編號。

語法

AwsStringOutcome GetSdkVersion()

參數

此動作沒有參數。

傳回值

如果成功， 會傳回目前SDK版本作為AwsStringOutcome物件。傳回的字串僅包含版本號碼 （例如 "3.1.5"）。如果不成功，則會傳回錯誤訊息。

範例

var getSdkVersionOutcome = GameLiftServerAPI.GetSdkVersion(); 

GetTerminationTime()

若設有終止時間，即傳回伺服器程序排定關閉的時間。伺服器程序會在從 Amazon GameLift 服務收到回onProcessTerminate()呼後採取此動作。Amazon GameLift 可能會onProcessTerminate()因為下列原因呼叫 ：（1） 運作狀態不佳 （伺服器程序已報告連接埠運作狀態或尚未回應 Amazon GameLift，（2） 在縮減規模事件期間終止執行個體時，或 （3） 執行個體因點執行個體中斷而終止時。

如果程序已收到回onProcessTerminate()呼，傳回的值為預估終止時間。如果程序尚未收到回onProcessTerminate()呼，則會傳回錯誤訊息。進一步了解關閉伺服器處理程序的相關資訊。

語法

AwsDateTimeOutcome GetTerminationTime()

參數

此動作沒有參數。

傳回值

如果成功， 會將終止時間傳回為AwsDateTimeOutcome物件。該值是終止時間，以自 0001 00：00：00 以來的已過勾號表示。例如，日期時間值 2020-09-13 12：26：40 -000Z 等於 637355968000000000 個點。如果沒有可用的終止時間， 會傳回錯誤訊息。

範例

var getTerminationTimeOutcome = GameLiftServerAPI.GetTerminationTime(); 

Init SDK（）

初始化 Amazon GameLift SDK。在任何其他 Amazon GameLift相關初始化發生之前，應該在啟動時呼叫此方法。

語法

InitSDKOutcome InitSDK()

參數

此動作沒有參數。

傳回值

如果成功， 會傳回 InitSdkOutcome 物件，指出伺服器程序已準備好呼叫 ProcessReady()。

範例

var initSDKOutcome = GameLiftServerAPI.InitSDK(); 

ProcessEnding()

通知 Amazon GameLift 服務伺服器程序正在關閉。此方法應於所有其他清除作業 (包括關閉所有作用中遊戲工作階段) 之後呼叫。此方法應以結束代碼 0 結束，非零的結束代碼會導致該程序未徹底結束的事件訊息出現。

一旦方法以 0 的程式碼結束，您就可以使用成功的結束程式碼終止程序。您也可以使用錯誤碼結束程序。如果您使用錯誤碼結束，機群事件將指出程序異常終止 （SERVER_PROCESS_TERMINATED_UNHEALTHY）。

語法

GenericOutcome ProcessEnding()

參數

此動作沒有參數。

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

var processEndingOutcome = GameLiftServerAPI.ProcessEnding();
if (processReadyOutcome.Success)
   Environment.Exit(0);
// otherwise, exit with error code
Environment.Exit(errorCode);
    

ProcessReady()

通知 Amazon GameLift 服務伺服器程序已準備好託管遊戲工作階段。在成功叫用Init SDK（）並完成伺服器程序可以託管遊戲工作階段之前所需的設定任務之後，呼叫此方法。此方法每個程序只能呼叫一次。

語法

GenericOutcome ProcessReady(ProcessParameters processParameters)

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

此範例會說明 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();
}

bool OnHealthCheck()
{
    bool isHealthy;
    // complete health evaluation within 60 seconds and set health
    return isHealthy;
}

RemovePlayerSession()

通知 Amazon GameLift 服務，具有指定播放器工作階段 ID 的播放器已中斷與伺服器程序的連線。作為回應，Amazon 會將播放器插槽 GameLift 變更為可用，以便將其指派給新的播放器。

語法

GenericOutcome RemovePlayerSession(String playerSessionId)

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

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

StartMatchBackfill()

傳送請求，以尋找使用 建立的遊戲工作階段中開放插槽的新玩家 FlexMatch。請同時參閱 動作 AWS SDKStartMatchBackfill（）。使用此動作，目前代管遊戲工作階段的遊戲伺服器程序即可初始化配對回填請求。進一步了解FlexMatch 回填功能 。

此為非同步動作。如果新的玩家成功比對，Amazon GameLift 服務會使用回呼函數 提供更新的比對器資料OnUpdateGameSession()。

一個伺服器程序一次僅能有一個使用中的配對回填請求。若要發送新請求，請先呼叫 StopMatchBackfill() 取消原始請求。

語法

StartMatchBackfillOutcome StartMatchBackfill (StartMatchBackfillRequest startBackfillRequest);

參數

傳回值

傳回具有相符回填票證 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 SDK 動作 StopMatchmaking（）。進一步了解 FlexMatch 回填功能 。

語法

GenericOutcome StopMatchBackfill (StopMatchBackfillRequest stopBackfillRequest);

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

// 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()遊戲工作階段結束後呼叫 。

通知 Amazon GameLift 服務伺服器程序已結束目前的遊戲工作階段。當伺服器程序保持作用中狀態並準備好託管新的遊戲工作階段時，就會呼叫此動作。只有在您的遊戲工作階段終止程序完成後，才應該呼叫它，因為它會向 Amazon 發出訊號 GameLift ，表示伺服器程序可立即用於託管新的遊戲工作階段。

如果在遊戲工作階段停止後伺服器程序將會關閉，則不會呼叫此動作。相反地，呼叫 ProcessEnding() 來表示遊戲工作階段和伺服器程序都已結束。

語法

GenericOutcome TerminateGameSession()

參數

此動作沒有參數。

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

此範例說明遊戲工作階段結束時的伺服器程序。

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

更新目前遊戲工作階段的能力，以接受新的玩家工作階段。遊戲工作階段可設定為接受或拒絕所有新的玩家工作階段。（另請參閱 Amazon GameLift Service API參考 中的 UpdateGameSession（） 動作）。

語法

GenericOutcome UpdatePlayerSessionCreationPolicy(PlayerSessionCreationPolicy playerSessionPolicy)

參數

傳回值

傳回一般結果，其中包含成功或失敗以及錯誤訊息。

範例

此範例設定目前遊戲工作階段的加入政策為可接受所有玩家。

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