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

# Alterando layouts de controles por toque com base no estado do jogo

> Alterando layouts de controles por toque com base no estado do jogo

Os jogos podem alterar o layout de toque exibido ao jogador ou modificar o estado usado por um layout exibido no momento. Os dois métodos podem ser usados em conjunto para criar a experiência mais natural para os jogadores.

**[Alterando layouts](#change_layout)**

A alteração de layouts deve ser usada ao:

* Fazer a transição entre diferentes esquemas de controle (por exemplo, dirigir um veículo e jogo de tiro em primeira pessoa)
* Ocultar temporariamente o layout de toque (para ter uma experiência totalmente por toque, habilitar uma experiência cinematográfica etc.)

**[Alterando o estado](#change_state)**

A alteração do estado do jogo incluído na parte de contexto do pacote de adaptação por toque deve ser usada ao:

* Modificar as imagens/iconografia dos controles com base no estado atual do jogo do jogador. Alguns exemplos incluem:
  * Alterar a imagem do botão de disparo com base na arma selecionada pelo jogador.
  * Alterar as imagens das habilidades com base nos itens que o jogador tem atualmente no inventário.
* Modificar o estado visual (visibilidade e habilitação) dos controles com base no estado atual do jogo do jogador. Alguns exemplos incluem:
  * Desabilitar o botão de recarregar quando o jogador não tiver munição adicional.
  * Tornar o botão de interação visível quando o jogador se aproximar de um item com o qual possa interagir (e invisível quando ele se afastar).

<a id="change_layout" />

## Alterando layouts em tempo de execução

**Mostrando um layout especificado**
O jogo deve usar a API [`XGameStreamingShowTouchControlLayout`](/pt-BR/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout) para mostrar um novo layout.

**Ocultando o layout atual**
O jogo deve usar a API [`XGameStreamingHideTouchControls`](/pt-BR/reference/system/xgamestreaming/functions/xgamestreaminghidetouchcontrols) para ocultar o layout exibido no momento.

Exemplo de como um jogo pode definir o layout com base no estado atual do jogo:

```C++ theme={null}
void OnGameStateChanged(GameState newState)
{
    // Toggle to the set of touch overlay controls which best match the new state of the game
    switch (newState)
    {
    case GameState::FirstPersonAction:
        XGameStreamingShowTouchControlLayout("FirstPersonAction");
        break;
    case GameState::Driving:
        XGameStreamingShowTouchControlLayout("Driving");
        break;
    case GameState::CutScene:
        // Don't show any touch overlay controls while the cut scene is rendering
        XGameStreamingHideTouchControls();
        break;
    }
}
```

<a id="change_state" />

## Alterando o estado em tempo de execução

O estado inicial na inicialização do jogo é definido pelo [estado padrão](/pt-BR/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-bundle#context) incluído no Pacote de Adaptação por Toque. No layout de controles por toque, o controle deve referenciar o estado da propriedade que pode ser alterada em tempo de execução.

O jogo pode utilizar a API `XGameStreamingUpdateTouchControlsState` para atualizar o estado durante a execução.

Por exemplo, o seguinte seria usado para ter um controle de "recarregar" que começa desabilitado, mas é habilitado quando o jogador deve ter essa capacidade.

```JSON theme={null}
//Example context file
{
  "$schema": "https://raw.githubusercontent.com/microsoft/xbox-game-streaming-tools/main/touch-adaptation-kit/schemas/context/v3.0/context.json",

  "state": {
    "enableReload": false
  }
}

//Example control in the layout:
{
    "type": "button",
    "action": "leftBumper",
    "enabled": {
        "$ref": "../../context.json#/state/enableReload"
    }
    ...
}
```

O jogo faria as chamadas de API para atualizar o estado:

```C++ theme={null}

// In this example, after the player has switched their active weapon - the game updates the
// enabled state of reload based on whether the player has extra magazines.
//
// Assumes passing in game structure that includes the active weapon with appropriate state.
//

void GameStreamingClientManager::UpdateStateAfterItemsChange(const playerWeapon& playerWeapon)
{
    // create an update for whether the reload button should be enabled
    XGameStreamingTouchControlsStateOperation reloadEnabled;
    reloadEnabled.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    reloadEnabled.path = "/enableReload";
    reloadEnabled.valueKind = XGameStreamingTouchControlsStateValueKind::Bool;
    reloadEnabled.booleanValue = playerWeapon.activeWeapon.reloadClips > 0;

    // combine all the updates into the update state call and make the call
    XGameStreamingTouchControlsStateOperation[1] updateOperations = {reloadEnabled};

    XGameStreamingUpdateTouchControlsState(updateOperations, _countof(updateOperations));
}
```


## Related topics

- [Requisitos do XBOX para jogos do XBOX](/pt-BR/publishing/certification/xbox-requirements.md)
- [XR-112 Estabelecimento de um usuário e um controle durante a ativação inicial e a retomada](/pt-BR/publishing/certification/xr/xr-112.md)
- [XR-052 Estado do usuário e local de salvamento do título, roaming e dependências](/pt-BR/publishing/certification/xr/xr-052.md)
- [Requisitos XBOX testados na certificação para jogos de console XBOX](/pt-BR/publishing/certification/console-cert-tested-requirements.md)
- [XR-115 Adição e remoção de usuários ou controles durante a jogabilidade](/pt-BR/publishing/certification/xr/xr-115.md)