Skip to main content

XGameRuntimeInitializeWithOptions

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

語法

參數

options _In_
類型:XGameRuntimeOptions*
指向選項結構的指標,該結構可修改執行階段的初始化方式。

傳回值

類型:HRESULT 如果成功,則傳回 S_OK;否則傳回錯誤碼。如需錯誤碼清單,請參閱錯誤碼。如果函式因找不到 Gaming Runtime 程式庫 (xgameruntime.dll) 而失敗,傳回值會設為 E_GAMERUNTIME_DLL_NOT_FOUND。

備註

下列範例示範如何使用遊戲編輯器或其他中介軟體,在同一個處理序中載入並執行多個遊戲。此範例假設有下列外部程式碼:
  • 名為「GameEngine」的類別,會接受遊戲檔案的路徑並啟動遊戲。這與遊戲引擎「播放器」在執行階段使用的引擎相同。
  • 此類別的執行個體會以全域變數的形式儲存在編輯器中,並代表目前的遊戲。
如下所示,執行階段可以使用不同的遊戲設定進行初始化。在取消初始化之後,也可以使用不同的遊戲設定重新初始化。
初始化
執行階段有兩層初始化:元件所連結的 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
XGameRuntimeInitialize
XGameRuntimeInit
使用 Gaming Runtime 開發新遊戲
Last modified on October 6, 2026