Amazon GameLift Server SDK 5.x for C# 和 Unity

您可以使用此 Amazon GameLift C# 伺服器 SDK 5.x 參考來協助您準備多人遊戲，以便與 Amazon 搭配使用 GameLift。如需整合程序的詳細資訊，請參閱將 Amazon GameLift 新增至您的遊戲伺服器和以取得使用 Unity 的 C# 伺服器SDK外掛程式的相關資訊，請參閱將 Amazon GameLift 整合至 Unity 專案。Amazon GameLift Server SDK 5.x for C# 支援。NET 4.6 和。NET 6.

主題

C# 和 Unity SDK的 Amazon GameLift 伺服器：動作

此 Amazon GameLift C# 伺服器SDK參考可協助您準備多人遊戲，以便與 Amazon 搭配使用 GameLift。如需整合程序的詳細資訊，請參閱將 Amazon GameLift 新增至您的遊戲伺服器和以取得使用 Unity 的 C# 伺服器SDK外掛程式的相關資訊，請參閱將 Amazon GameLift 整合至 Unity 專案。

動作

GetSdkVersion()
Init SDK（）
Init SDK（）
ProcessReady()
ProcessEnding()
ActivateGameSession()
UpdatePlayerSessionCreationPolicy()
GetGameSessionId()
GetTerminationTime()
AcceptPlayerSession()
RemovePlayerSession()
DescribePlayerSessions()
StartMatchBackfill()
StopMatchBackfill()
GetComputeCertificate()
GetFleetRoleCredentials()
Destroy（）

GetSdkVersion()

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

語法


AwsStringOutcome GetSdkVersion();

傳回值

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

範例


var getSdkVersionOutcome = GameLiftServerAPI.GetSdkVersion();

Init SDK（）

初始化受管EC2機群的 Amazon GameLift SDK。在與 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();

Init SDK（）

初始化的 Amazon GameLift SDK Anywhere 機群。在與 Amazon 相關的任何其他初始化 GameLift 發生之前，請在啟動時呼叫此方法。此方法需要明確的伺服器參數，才能設定伺服器與 Amazon GameLift 服務之間的通訊。

語法


GenericOutcome InitSDK(ServerParameters serverParameters);

參數

ServerParameters

在 Amazon 上初始化遊戲伺服器 GameLift Anywhere 機群，使用下列資訊建構ServerParameters物件：

URL WebSocket 用於連線至遊戲伺服器的。
用於託管遊戲伺服器的程序 ID。
託管遊戲伺服器程序的運算 ID。
包含 Amazon 的 Amazon GameLift 機群 ID GameLift Anywhere 運算。
Amazon GameLift 操作產生的授權權杖。

傳回值

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

注意

如果針對部署到 Anywhere 機群的遊戲組建呼叫呼叫InitSDK()失敗，請檢查建立組建資源時使用的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()

通知 Amazon GameLift 伺服器程序已準備好託管遊戲工作階段。叫用後呼叫此方法Init SDK（）。此方法每個程序只能呼叫一次。

語法


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 伺服器程序正在終止。在所有其他清除任務（包括關閉作用中的遊戲工作階段）之後，以及在終止程序之前呼叫此方法。根據的結果ProcessEnding()，程序會成功（0）或錯誤（-1）結束並產生機群事件。如果程序因錯誤終止，產生的機群事件為 SERVER_PROCESS_TERMINATED_UNHEALTHY。

語法


GenericOutcome ProcessEnding()

傳回值

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

範例

此範例會呼叫 ProcessEnding()和，Destroy()然後以成功或錯誤結束碼終止伺服器程序。


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

傳回值

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

範例

此範例顯示的是做為 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。
在縮減規模事件期間終止執行個體時。
當執行個體因 Spot-instance 中斷而終止時。

語法


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 變更為 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 播放器已中斷與伺服器程序的連線。為了回應，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 會使用回呼函數 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：包含根憑證和中繼憑證的憑證鏈。
- rootCertificate.pem：根憑證。
- privateKey.pem：最終使用者憑證的私有金鑰。
ComputeName：運算資源的名稱。

範例


GetComputeCertificateOutcome getComputeCertificateOutcome = GameLiftServerAPI.GetComputeCertificate();

GetFleetRoleCredentials()

擷取授權 Amazon 與其他 GameLift 互動IAM的角色憑證 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);

Destroy（）

從記憶體中SDK釋放 Amazon GameLift 遊戲伺服器。最佳實務是在終止程序之後ProcessEnding()和之前呼叫此方法。如果您使用的是 Anywhere 機群，而且沒有在每次遊戲工作階段後終止伺服器程序，請呼叫 Destroy()，然後在通知 Amazon GameLift 程序已準備好使用託管遊戲工作階段之前InitSDK()重新初始化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); 
  }

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

資料類型