> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 初始化 GDK

> 將遊戲從 Steamworks 移植到 GDK 時，設定 MicrosoftGame.config、初始化 Gaming Runtime 和 XSAPI，並將使用者登入 XBOX Live。

將 Steamworks 新增至遊戲專案之後，若要開始使用它，您需要呼叫 `SteamAPI_Init` 函式來初始化 API。您也可以選擇呼叫 `SteamAPI_RestartAppIfNecessary`，在必要時透過 Steam 重新啟動應用程式。初始化 XBOX Game Development Kit (GDK) 會稍微複雜一些，因為它不像 Steam 那樣有一個統一的應用程式，用來啟動遊戲並與不同的遊戲服務進行通訊。

若要開始使用 XBOX Game Development Kit (GDK) 中的 API，您需要使用下列步驟。

1. 將 *MicrosoftGame.config* 檔案新增至您的專案。
2. 初始化 Gaming Runtime 服務。
3. 初始化 XBOX Services API，以便呼叫 XBOX Live 取得使用者身分識別、雲端存檔、成就等功能。
4. 將使用者登入 XBOX Live。儲存成功登入後傳回的控制代碼和 XBOX 使用者識別碼 (XUID)，以供日後使用。

<Note>
  在 Steam 上，您可以在載入時存取使用者的 Steam ID 和所有 API，因為從其服務啟動遊戲時，Steam 啟動器會自動插入使用者的帳戶資訊。XBOX Live API 由多個啟動器上的遊戲使用，因此您無法自動取得這些資訊。您需要在啟動時手動將使用者登入。
</Note>

如需如何執行步驟 1 的相關資訊，請參閱 [MicrosoftGame.config 概觀](/zh-TW/build/core-features/common/game-config/MicrosoftGameConfig-Overview)。

您可以在[開始使用 XBOX Live API](/zh-TW/services/xbox-services/index) 中找到如何執行步驟 2–4 的相關資訊 (或參閱下列摘要)，並請務必一併實作該主題「清除 XSAPI」一節中所述的行為。初始化 Gaming Runtime 和 XBOX Services API 之後，您就可以將使用者登入 XBOX Live。您不需要建立 `XTaskQueue`，因為如果您將其保留空白，系統會自動為您建立。

```cpp theme={null}
#include <XGameRuntimeInit.h>
#include <XTaskQueue.h>
#include <xsapi-c/services_c.h>

// ...

void InitializeXboxLive()
{
    // ...
    HRESULT hr = XGameRuntimeInitialize();
    if (FAILED(hr))
    {
        // handle error: couldn't initialize the Gaming Runtime service.
    }

    XblInitArgs xblArgs = {};
    xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Add your SCID here that you got from the Partner Center web portal.

    HRESULT hr = XblInitialize(&xblArgs);
    if (FAILED(hr))
    {
        // handle error: couldn't initialize XBOX Live.
    }
    // ...
}
```

## 將使用者登入 XBOX Live

使用 [XUserAddAsync API](/zh-TW/build/core-features/common/user/xuser_howto_best_practice_signing_in) 將使用者登入 XBOX Live。如果這是他們第一次登入您的遊戲，系統會向他們顯示您的遊戲所要求的權限清單。他們需要明確授權這些權限，才能存取其 XBOX Live 帳戶。

他們成功登入之後，您可以使用傳入 [`XUserAddResult`](/zh-TW/reference/system/xuser/xuser_members) 函式的 `XUserHandle` 參考。它可用來取得該 XBOX Live 使用者的相關資訊，例如其玩家代號、玩家相片、登入狀態、年齡群組和權限。

使用者第一次登入之後，如果自上次啟動遊戲以來不需要處理 UI 提示 (例如新的隱私權合約)，他們應該就能以無訊息方式成功登入 (也就是說，不需要他們採取任何動作)。不過，您仍然需要進行這些 API 呼叫，才能取得身分識別存取權。

呼叫 XBOX Live API 時需要 `XblContextHandle`。您可以使用 [XblContextCreateHandle](/zh-TW/reference/live/xsapi-c/xbox_live_context_c/xbox_live_context_c_members) 函式，透過 `XUserHandle` 取得 `XblContextHandle`。


## Related topics

- [將 GDK 與自訂 C/C++ 引擎整合](/zh-TW/build/gdk-and-engines/custom-engine.md)
- [Steam 移植指南概觀](/zh-TW/build/steam-porting-guide/overview.md)
- [偵測網路初始化狀態](/zh-TW/build/console-features/networking/initialization-connectivity-networking.md)
- [目標工作階段初始化和 QoS](/zh-TW/services/xbox-services/multiplayer/matchmaking/concepts/live-matchmaking-target-session.md)
- [XGameStreaming](/zh-TW/reference/system/xgamestreaming/xgamestreaming_members.md)