> ## 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](/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize) 方法，但某些游戏引擎或中间件可能需要更可配置的初始化。

## Syntax

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

### Parameters

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

指向选项结构的指针，该结构可以修改运行时的初始化方式。

### Return value

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

如果成功，则返回 **S\_OK**；否则返回错误代码。有关错误代码的列表，请参阅[错误代码](/reference/errorcodes)。如果由于找不到 Gaming Runtime 库 (xgameruntime.dll) 而导致该函数失败，则返回值设置为 **E\_GAMERUNTIME\_DLL\_NOT\_FOUND**。

## Remarks

以下示例演示如何使用游戏编辑器或其他中间件在同一进程中加载并运行多个游戏。它假定有以下外部代码：

* 一个名为 “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。

## Requirements

**头文件：** XGameRuntimeInit.h

**库：** xgameruntime.lib

**受支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## See also

[XGameRuntimeUninitialize](/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize)\
[XGameRuntimeInitialize](/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize)\
[XGameRuntimeInit](/reference/system/xgameruntimeinit/xgameruntimeinit_members)\
[使用 Gaming Runtime 开发新标题](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/gr-developing-new-titles-on-gamecore)


## Related topics

- [XGameRuntimeInitialize](/zh-CN/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize.md)
- [XGameRuntimeOptions](/zh-CN/reference/system/xgameruntimeinit/Structures/xgameruntimeoptions.md)
- [XGameRuntimeGameConfigSource](/zh-CN/reference/system/xgameruntimeinit/Enumerations/xgameruntimegameconfigsource.md)
- [XGameRuntimeInit](/zh-CN/reference/system/xgameruntimeinit/xgameruntimeinit_members.md)
- [XGameRuntimeUninitialize](/zh-CN/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize.md)