> ## 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」というクラス。これはゲーム エンジンの「player」により実行時に使用されるのと同じエンジンです。
* このインスタンスはエディター内でグローバルとして格納され、現在のゲームを表します。

以下に示すように、ランタイムは異なるゲーム構成で初期化できます。また、初期化解除後に異なるゲーム構成で再初期化することもできます。

```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); 
}
```

**Initialization**\
ランタイムには 2 つの初期化レイヤーがあります。コンポーネントがリンクする 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 のようなファイル I/O エラーは、診断を容易にするため E\_GAMERUNTIME\_GAMECONFIG\_BAD\_FORMAT には変換されません。

**Uninitialization**\
ここにも 2 つのレイヤーがあります。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)\
[Developing new titles using Gaming Runtime](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/pc-dev/overviews/gr-developing-new-titles-on-gamecore)


## Related topics

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