XGameRuntimeInitializeWithOptions

此 API 初始化游戏运行时，获取指向选项结构的指针，该结构可以修改运行时的初始化方式。 虽然游戏通常应继续利用现有的 XGameRuntimeInitialize 方法，但某些游戏引擎或中间件可能需要进行更可配置的初始化。

语法

HRESULT XGameRuntimeInitializeWithOptions(
    _In_ const XGameRuntimeOptions* options
)  

参数

options _In_
类型：XGameRuntimeOptions*

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

返回值

类型：HRESULT

如果成功，则返回 S_OK；否则返回错误代码。 有关错误代码的列表，请参阅错误代码。 如果函数由于未找到游戏运行时库 (xgameruntime.dll) 而失败，则将返回值设置为 E_GAMERUNTIME_DLL_NOT_FOUND。

备注

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

• 一个名为“GameEngine”的类，它采用游戏文件的路径并启动游戏。 这是游戏引擎“player”在运行时使用的相同引擎。
• 此实例以全局形式存储在编辑器中，表示当前游戏。

可以使用不同的游戏配置初始化运行时，如下所示。 取消初始化后，也可以使用其他游戏配置重新初始化它。

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 refcount 达到零时仍有活动运行时对象，则合并 DLL 可能会失败。 如果发生这种情况，运行时将：

• 不卸载运行时 DLL，因为这可能会导致崩溃。
• 存储错误，以便稍后在将来调用 XGameRuntimeInitialize 时返回该错误*
• 发出 XErrorReport。

请注意，由于此行为，取消初始化失败是终端：运行时不再初始化，尝试初始化运行时将始终失败。

当游戏运行时未初始化时，游戏应关闭所有句柄。 任何保持打开的句柄都被视为内存泄漏。 尝试使用从之前初始化运行时泄漏的任何句柄将返回E_GAMERUNTIME_INVALID_HANDLE。

要求

头文件：XGameRuntimeInit.h

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XGameRuntimeUninitialize
XGameRuntimeInitialize
XGameRuntimeInit
使用游戏运行时开发新游戏