Skip to main content

XGameRuntimeInitializeWithOptions

この API は、ランタイムの初期化方法を変更できるオプション構造体へのポインターを受け取り、ゲーム ランタイムを初期化します。通常、ゲームは引き続き既存の XGameRuntimeInitialize メソッドを利用するべきですが、一部のゲーム エンジンやミドルウェアでは、より構成可能な初期化が必要になる場合があります。

Syntax

Parameters

options _In_
型: XGameRuntimeOptions*
ランタイムの初期化方法を変更できるオプション構造体へのポインター。

Return value

型: HRESULT 成功した場合は S_OK を返します。それ以外の場合はエラー コードを返します。エラー コードの一覧については、エラー コードを参照してください。Gaming Runtime ライブラリ (xgameruntime.dll) が見つからなかったために関数が失敗した場合、戻り値は E_GAMERUNTIME_DLL_NOT_FOUND に設定されます。

Remarks

次の例は、ゲーム エディターやその他のミドルウェアを使用して、同じプロセスで複数のゲームを読み込んで実行する方法を示しています。次の外部コードを前提としています。
  • ゲーム ファイルへのパスを受け取ってゲームを開始する「GameEngine」というクラス。これはゲーム エンジンの「player」により実行時に使用されるのと同じエンジンです。
  • このインスタンスはエディター内でグローバルとして格納され、現在のゲームを表します。
以下に示すように、ランタイムは異なるゲーム構成で初期化できます。また、初期化解除後に異なるゲーム構成で再初期化することもできます。
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
XGameRuntimeInitialize
XGameRuntimeInit
Developing new titles using Gaming Runtime
最終更新日 2026年8月24日