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

# 根據遊戲狀態變更觸控控制配置

> 根據遊戲狀態變更觸控控制配置

遊戲能夠變更向玩家顯示的觸控配置，或修改目前顯示的配置所使用的狀態。這兩種方法可以一起使用，為玩家打造最自然的體驗。

**[變更配置](#change_layout)**

在下列情況下應使用變更配置：

* 在不同的控制配置之間轉換 (例如，駕駛車輛和第一人稱射擊)
* 暫時隱藏觸控配置 (以提供完整的觸控體驗、啟用電影般的體驗等)

**[變更狀態](#change_state)**

在下列情況下，應變更觸控調整組合之內容 (context) 部分所包含的遊戲狀態：

* 根據玩家目前的遊戲狀態修改控制項的影像/圖示。範例包括：
  * 根據玩家選取的武器變更開火按鈕上的影像。
  * 根據玩家目前物品欄中的物品變更能力的影像。
* 根據玩家目前的遊戲狀態修改控制項的視覺狀態 (可見性和啟用)。範例包括：
  * 當玩家沒有額外彈藥時停用重新裝填按鈕。
  * 當玩家接近可互動的物品時讓互動按鈕可見 (並在玩家離開時使其不可見)。

<a id="change_layout" />

## 在執行階段變更配置

**顯示指定的配置**
遊戲應使用 [`XGameStreamingShowTouchControlLayout`](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout) API 來顯示新的配置。

**隱藏目前的配置**
遊戲應使用 [`XGameStreamingHideTouchControls`](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminghidetouchcontrols) API 來隱藏目前顯示的配置。

遊戲如何根據目前遊戲狀態設定配置的範例：

```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" />

## 在執行階段變更狀態

遊戲啟動時的初始狀態是由觸控調整組合中所包含的[預設狀態](/zh-TW/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-bundle#context)所定義。在觸控控制配置中，控制項應針對可能在執行階段變更的屬性參考該狀態。

遊戲可以使用 `XGameStreamingUpdateTouchControlsState` API 在執行階段更新狀態。

例如，下列內容可用來建立一開始為停用狀態的「重新裝填」控制項，並在玩家應具備該能力時將其啟用。

```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"
    }
    ...
}
```

遊戲會進行 API 呼叫來更新狀態：

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

- [XBOX 主機遊戲的認證測試 XBOX 需求](/zh-TW/publishing/certification/console-cert-tested-requirements.md)
- [XR-003 提交的遊戲品質](/zh-TW/publishing/certification/xr/xr-003.md)
- [XR052 使用者狀態與遊戲存檔位置、漫遊及相依性](/zh-TW/publishing/certification/fma/xr-052.md)
- [XR112 在初次啟用與繼續時建立使用者和控制器](/zh-TW/publishing/certification/fma/xr-112.md)
- [最常失敗的測試案例](/zh-TW/publishing/certification/xr-top-failing.md)