> ## 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

Essa API inicializa o runtime do jogo, recebendo um ponteiro para uma estrutura de opções que pode modificar a forma como o runtime é inicializado. Embora os jogos normalmente devam continuar usando o método existente [XGameRuntimeInitialize](/pt-BR/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize), alguns mecanismos de jogo ou middleware podem precisar de uma inicialização mais configurável.

## Sintaxe

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

### Parâmetros

*options* \_In\_\
Tipo: XGameRuntimeOptions\*

Ponteiro para uma estrutura de opções que pode modificar a forma como o runtime é inicializado.

### Valor retornado

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

Retornará **S\_OK** se for bem-sucedido; caso contrário, retornará um código de erro. Para obter uma lista de códigos de erro, consulte [Códigos de erro](/pt-BR/reference/errorcodes). Se a função falhar porque a biblioteca do Gaming Runtime (xgameruntime.dll) não foi encontrada, o valor retornado será definido como **E\_GAMERUNTIME\_DLL\_NOT\_FOUND**.

## Comentários

O exemplo a seguir demonstra como um editor de jogos ou outro middleware pode ser usado para carregar e executar vários jogos no mesmo processo. Ele pressupõe o seguinte código externo:

* Uma classe chamada "GameEngine" que recebe o caminho para os arquivos do jogo e inicia o jogo.  É o mesmo mecanismo usado em runtime pelo "player" do mecanismo de jogo.
* Uma instância dela é armazenada como global no editor e representa o jogo atual.

O runtime pode ser inicializado com uma configuração de jogo diferente, conforme mostrado abaixo.  Ele também pode ser reinicializado com uma configuração de jogo diferente após o cancelamento da inicialização.

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

**Inicialização**\
O runtime tem duas camadas de inicialização: XGameRuntime.lib, à qual um componente é vinculado, e XGameRuntime.dll, que é a implementação real do runtime.  Quando XGameRuntime.lib é inicializada, ela carrega XGameRuntime.dll e a inicializa. A inicialização da DLL tem contagem de referências, permitindo que várias bibliotecas se conectem. A inicialização da biblioteca não tem contagem de referências: várias chamadas para inicializá-la são ignoradas (embora, se XGameRuntimeInitializeWithOptions for chamada, as opções fornecidas sejam comparadas com as opções inicializadas atualmente e E\_GAMERUNTIME\_OPTIONS\_MISMATCH seja retornado se forem diferentes).

Cada API de inicialização tem o seguinte comportamento:

* **XGameRuntimeInitialize**: se a DLL do runtime já tiver sido inicializada por outra chamada, essa API "adota" as opções de inicialização fornecidas na outra chamada. Se for a primeira vez que o runtime é inicializado, valores padrão serão usados para as opções de inicialização. Os jogos devem sempre inicializar o runtime usando essa API.
* **XGameRuntimeInitializeWithOptions**: todos os componentes que inicializam o runtime devem passar as mesmas opções se usarem esse método. Se o runtime tiver sido inicializado anteriormente com outro conjunto de opções, essa chamada falhará com E\_GAMERUNTIME\_OPTIONS\_MISMATCH. Componentes de middleware, como um editor de jogos Unity, podem usar essa API para inicializar o runtime com um GameConfig personalizado antes de iniciar o jogo.
  O runtime pode ser reinicializado com opções diferentes se primeiro tiver sua inicialização totalmente cancelada. Isso exige que todos os módulos que chamaram um dos métodos XGameRuntimeInitialize\* chamem XGameRuntimeUninitialize.

Se o jogo for empacotado em um XVC ou MSIXVC, todas as opções personalizadas fornecidas deverão corresponder às configurações da configuração de jogo do pacote. Caso contrário, a chamada de inicialização falhará com E\_GAMERUNTIME\_OPTIONS\_NOT\_SUPPORTED.

Observe que ERROR\_NOT\_FOUND da configuração de jogo não conta como falha, pois atualmente há cenários em que o runtime é inicializado fora de jogos. Erros de E/S de arquivo, como FILE\_NOT\_FOUND, não são transformados em E\_GAMERUNTIME\_GAMECONFIG\_BAD\_FORMAT para ajudar no diagnóstico.

**Cancelamento da inicialização**\
Aqui também há duas camadas. Cancelar a inicialização de XgameRuntime.lib cancelará a inicialização da biblioteca e liberará sua referência na DLL. Outras chamadas de cancelamento de inicialização para a biblioteca serão ignoradas até que a biblioteca seja reinicializada.

Cancelar a inicialização da DLL decrementa a contagem de referências.  Quando ela chega a zero, a inicialização da DLL é cancelada. Esse comportamento permanece o mesmo.

O cancelamento da inicialização da DLL poderá falhar se ainda houver objetos de runtime ativos quando a contagem de referências da DLL chegar a zero. Se isso acontecer, o runtime:

* Não descarregará a DLL do runtime, pois isso pode causar uma falha.
* Armazenará o erro para retorná-lo posteriormente em uma chamada futura para XGameRuntimeInitialize\*
* Emitirá um XErrorReport.

Observe que, devido a esse comportamento, uma falha no cancelamento da inicialização é terminal: o runtime não está mais inicializado e as tentativas de inicializá-lo sempre falharão.

Quando a inicialização do runtime do jogo for cancelada, todos os identificadores deverão ser fechados pelo jogo. Quaisquer identificadores deixados abertos são considerados vazamentos de memória. Tentar usar qualquer identificador vazado de uma inicialização anterior do runtime retornará E\_GAMERUNTIME\_INVALID\_HANDLE.

## Requisitos

**Cabeçalho:** XGameRuntimeInit.h

**Biblioteca:** xgameruntime.lib

**Plataformas com suporte:** Windows, consoles da família XBOX One e consoles XBOX Series

## Confira também

[XGameRuntimeUninitialize](/pt-BR/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize)\
[XGameRuntimeInitialize](/pt-BR/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize)\
[XGameRuntimeInit](/pt-BR/reference/system/xgameruntimeinit/xgameruntimeinit_members)\
[Desenvolvendo novos títulos usando o Gaming Runtime](/pt-BR/build/gdk-and-engines/guides/gdk-project-templates)


## Related topics

- [XGameRuntimeInitializeWithOptions](/reference/system/xgameruntimeinit/functions/xgameruntimeinitializewithoptions.md)
- [XGameRuntimeInitialize](/reference/system/xgameruntimeinit/functions/xgameruntimeinitialize.md)
- [XGameRuntimeOptions](/reference/system/xgameruntimeinit/Structures/xgameruntimeoptions.md)