> ## 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.

# XGameRuntimeInitializeWithOptions

> XGameRuntimeInitializeWithOptions

# XGameRuntimeInitializeWithOptions

此 API 會初始化遊戲執行階段，並接受指向選項結構的指標，該結構可修改執行階段的初始化方式。雖然遊戲通常應繼續使用現有的 [XGameRuntimeInitialize](/zh-TW/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize) 方法，但某些遊戲引擎或中介軟體可能需要更具可設定性的初始化。

## 語法

```cpp theme={null}
HRESULT XGameRuntimeInitializeWithOptions(
    _In_ const XGameRuntimeOptions* options
)  
```

### 參數

*options* \_In\_\
類型：XGameRuntimeOptions\*

指向選項結構的指標，該結構可修改執行階段的初始化方式。

### 傳回值

類型：[HRESULT](https://learn.microsoft.com/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a)

如果成功，則傳回 **S\_OK**；否則傳回錯誤碼。如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。如果函式因找不到 Gaming Runtime 程式庫 (xgameruntime.dll) 而失敗，傳回值會設為 **E\_GAMERUNTIME\_DLL\_NOT\_FOUND**。

## 備註

下列範例示範如何使用遊戲編輯器或其他中介軟體，在同一個處理序中載入並執行多個遊戲。此範例假設有下列外部程式碼：

* 名為「GameEngine」的類別，會接受遊戲檔案的路徑並啟動遊戲。這與遊戲引擎「播放器」在執行階段使用的引擎相同。
* 此類別的執行個體會以全域變數的形式儲存在編輯器中，並代表目前的遊戲。

如下所示，執行階段可以使用不同的遊戲設定進行初始化。在取消初始化之後，也可以使用不同的遊戲設定重新初始化。

```cpp theme={null}
void StartGame(const char* gamePath) 
{ 
    // If there is an existing game running, shut it down 
    if (g_game.IsRunning()) 
    { 
        g_game.Stop() 
    } 
 
    // Initialize the runtime in this process for this path 
    std::string gameConfig(gamePath); 
    gameConfig.append(“\\MicrosoftGame.config”); 
    XGameRuntimeOptions options{}; 
    options.gameConfigSource = XGameRuntimeGameConfigSource::File; 
    options.gameConfig = gameConfig.c_str(); 
    THROW_IF_FAILED(XGameRuntimeInitializeWithOptions(&options)); 
 
    // Now launch the game normally. 
    GameEngine game; 
    game.Launch(gamePath); 
    g_game = std::move(game); 
} 
 

// Examples of Launch / Stop behavior in GameEngine 
void GameEngine::Stop() 
{ 
    // Disconnect all globals from the runtime, closing handles and removing event 
    // handlers 

    // Handle game shut down before uninitializing the runtime

    XGameRuntimeUninitialize(); 
} 

void GameEngine::Launch(const char* gamePath) 
{ 
    // Standard XGameRuntimeInitialize here is fine to call – it will adopt the 
    // GameConfig settings from the earlier XGameRuntimeInitializeWithOptions call. 

    XGameRuntimeInitialize(); 
    RunGame(gamePath); 
}
```

**初始化**\
執行階段有兩層初始化：元件所連結的 XGameRuntime.lib，以及實際執行階段實作 XGameRuntime.dll。XGameRuntime.lib 初始化時，會載入 XGameRuntime.dll 並將其初始化。DLL 的初始化具有參考計數，允許多個程式庫連線。程式庫的初始化則沒有參考計數，多次呼叫初始化會被忽略 (不過如果呼叫 XGameRuntimeInitializeWithOptions，會將提供的選項與目前已初始化的選項進行比較，若兩者不同則傳回 E\_GAMERUNTIME\_OPTIONS\_MISMATCH)。

每個初始化 API 的行為如下：

* **XGameRuntimeInitialize**：如果執行階段 DLL 已由另一個呼叫初始化，此 API 會「沿用」另一個呼叫中提供的初始化選項。如果這是第一次初始化執行階段，則會使用預設值作為初始化選項。遊戲應一律使用此 API 來初始化執行階段。
* **XGameRuntimeInitializeWithOptions**：如果使用此方法，所有初始化執行階段的元件都必須傳遞相同的選項。如果執行階段先前已使用另一組選項初始化，此呼叫將會失敗並傳回 E\_GAMERUNTIME\_OPTIONS\_MISMATCH。Unity 遊戲編輯器等中介軟體元件可以使用此 API，在啟動遊戲之前以自訂 GameConfig 初始化執行階段。
  如果先完全取消初始化執行階段，就可以使用不同的選項重新初始化。這需要所有呼叫過任一 XGameRuntimeInitialize\* 方法的模組都呼叫 XGameRuntimeUninitialize。

如果遊戲已封裝為 XVC 或 MSIXVC，提供的任何自訂選項都必須與套件遊戲設定中的設定相符。如果不相符，初始化呼叫將會失敗並傳回 E\_GAMERUNTIME\_OPTIONS\_NOT\_SUPPORTED。

請注意，遊戲設定的 ERROR\_NOT\_FOUND 不會視為失敗，因為目前有些情況會在遊戲之外初始化執行階段。為了協助診斷，FILE\_NOT\_FOUND 等檔案 IO 錯誤不會轉換為 E\_GAMERUNTIME\_GAMECONFIG\_BAD\_FORMAT。

**取消初始化**\
這裡同樣有兩層。取消初始化 XgameRuntime.lib 會取消初始化程式庫，並釋放其對 DLL 的參考。在程式庫重新初始化之前，對程式庫的後續取消初始化呼叫都會被忽略。

取消初始化 DLL 會遞減參考計數。當計數為零時，DLL 就會取消初始化。此行為維持不變。

如果 DLL 參考計數達到零時仍有作用中的執行階段物件，取消初始化 DLL 可能會失敗。若發生這種情況，執行階段將會：

* 不卸載執行階段 DLL，因為這可能會導致當機。
* 儲存錯誤，以便稍後在後續的 XGameRuntimeInitialize\* 呼叫中傳回。
* 發出 XErrorReport。

請注意，由於此行為，取消初始化失敗是無法復原的：執行階段不再處於初始化狀態，嘗試初始化它一律會失敗。

取消初始化遊戲執行階段時，遊戲應關閉所有控制代碼。任何保持開啟的控制代碼都會被視為記憶體流失。嘗試使用先前執行階段初始化所洩漏的任何控制代碼，將會傳回 E\_GAMERUNTIME\_INVALID\_HANDLE。

## 需求

**標頭：** XGameRuntimeInit.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[XGameRuntimeUninitialize](/zh-TW/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize)\
[XGameRuntimeInitialize](/zh-TW/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize)\
[XGameRuntimeInit](/zh-TW/reference/system/xgameruntimeinit/xgameruntimeinit_members)\
[使用 Gaming Runtime 開發新遊戲](/zh-TW/build/gdk-and-engines/guides/gdk-project-templates)


## Related topics

- [XGameRuntimeInitializeWithOptions](/reference/system/xgameruntimeinit/functions/xgameruntimeinitializewithoptions.md)
- [XGameRuntimeInitialize](/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize.md)
- [XGameRuntimeOptions](/reference/system/xgameruntimeinit/Structures/xgameruntimeoptions.md)