XGameRuntimeInitializeWithOptions

[アーティクル]
06/20/2024

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

構文

HRESULT XGameRuntimeInitializeWithOptions(
    _In_ const XGameRuntimeOptions* options
)

パラメーター

options _In_
型: XGameRuntimeOptions*

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

戻り値

型: HRESULT

正常に実行された場合は S_OK が返され、それ以外の場合はエラーコードが返されます。エラーコードの一覧については、「エラーコード」を参照してください。ゲームランタイムライブラリ (xgameruntime.dll) が見つからないために関数が失敗した場合は、戻り値は E_GAMERUNTIME_DLL_NOT_FOUND に設定されます。

解説

次の例では、ゲームエディターまたはその他のミドルウェアを使用して、同じプロセスで複数のゲームを読み込んで実行する方法を示します。次の外部コードを前提としています。

ゲームファイルへのパスを取得し、ゲームを開始する "GameEngine" というクラス。これは、ゲームエンジン "プレイヤー" によって実行時に使用されるのと同じエンジンです。
このインスタンスは、エディターにグローバルとして格納され、現在のゲームを表します。

ランタイムは、次に示すように、別のゲーム構成で初期化できます。初期化を解除した後、別のゲーム構成で再初期化することもできます。

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 という 2 つの初期化レイヤーがあります。 XGameRuntime.lib が初期化されると、XGameRuntime.dll が読み込まれて初期化されます。 DLL の初期化は参照カウントされ、複数のライブラリを接続できます。ライブラリの初期化は参照カウントされません。初期化するための複数の呼び出しは無視されます (ただし、XGameRuntimeInitializeWithOptions が呼び出された場合、指定されたオプションは現在初期化されているオプションと比較され、異なる場合はE_GAMERUNTIME_OPTIONS_MISMATCHが返されます)。

各初期化 API には、次の動作があります。

XGameRuntimeInitialize: ランタイム DLL が既に別の呼び出しによって初期化されている場合、この API は、他の呼び出しで指定された初期化オプションに対して "floats" します。ランタイムが初めて初期化された場合は、初期化オプションに既定値が使用されます。ゲームは常に、この 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に変換されません。

初期化解除
ここにも 2 つのレイヤーがあります。 XgameRuntime.lib の初期化を解除すると、ライブラリが初期化解除され、DLL での参照がリリースされます。ライブラリのそれ以上の初期化解除呼び出しは、ライブラリが再初期化されるまで無視されます。

DLL の初期化を解除すると、ref カウントがデクリメントされます。 0 の場合、DLL は初期化されません。この動作は変わりません。

DLL 参照カウントが 0 に達してもアクティブなランタイムオブジェクトが存在する場合、DLL のユニタイアル化は失敗する可能性があります。この場合、ランタイムは次の処理を行います。

これによりクラッシュが発生する可能性があるため、ランタイム DLL をアンロードしないでください。
エラーを格納して、後で XGameRuntimeInitialize* を呼び出して後で返します。
XErrorReport が生成されます。

この動作により、初期化されていないエラーはターミナルです。ランタイムは初期化されなくなり、初期化を試みると常に失敗します。

ゲームランタイムが初期化されていない場合は、すべてのハンドルをゲームによって閉じる必要があります。開いたままのハンドルは、メモリリークと見なされます。ランタイムの以前の初期化からリークされたハンドルを使用しようとすると、E_GAMERUNTIME_INVALID_HANDLEが返されます。

要件

ヘッダー: XGameRuntimeInit.h

ライブラリ: xgameruntime.lib

サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体

次の方法で共有

XGameRuntimeInitializeWithOptions

構文

パラメーター

戻り値

解説

要件

関連項目

その他のリソース