触控适配布局的自定义资产

在你的触控适配布局中，在控件上提供语义图标是一种有效的方式，能向游戏玩家传达每个控件的用途。虽然熟悉 XBOX 控制器的玩家会快速理解常见的 A、B、X、Y 按钮，但如果控件显示它们将触发的操作，其他玩家可能会更容易理解你的触控。例如，与其在按钮上显示 XBOX A 图标，不如在按钮上显示一个跳跃人物的图像，这样能帮助玩家理解每个控件将执行什么操作。虽然你可以从内置的图标集中为你的控件选择，但你也可以使用与你游戏视觉美学相匹配的图案来自定义它们。这样做可以让你游戏的触控感觉更像是你游戏中不可分割的一部分，从而使玩游戏的体验对于移动设备来说感觉更加原生。例如，以下是使用标准图标构建的布局：

以下是使用自定义图案的相同布局：

当此布局加载到游戏上时，自定义美术有助于将触控的视觉风格与游戏的视觉风格联系起来。

资产文件

资产是 PNG 文件，需要在基础分辨率以及该基础分辨率的 1.5x、2.0x、3.0x 和 4.0x 缩放比例下提供。这样，流式传输客户端可以根据游戏正在流式传输设备的 DPI 来选择最佳版本的资产进行显示。每种资产类型的基础分辨率在下方列出。 Touch Adaptation Kit 支持资产本地化，使你能够根据你的游戏被流式传输到的设备的语言提供不同的资产。每个本地化版本的资产必须包含所有必需的分辨率。在磁盘上组织资产时，文件结构首先按语言组织，然后按资产比例组织。例如，你的文件结构可能如下所示：

assets/
    neutral/
        @1.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @1.5x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @2.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @3.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @4.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
    fr/
        fr-CA/
            @1.0x/
                JoystickKnobForeground.png
            @1.5x/
                JoystickKnobForeground.png
            @2.0x/
                JoystickKnobForeground.png
            @3.0x/
                JoystickKnobForeground.png
            @4.0x/
                JoystickKnobForeground.png
        @1.0x/
            JoystickKnobBackground.png
        @1.5x/
            JoystickKnobBackground.png
        @2.0x/
            JoystickKnobBackground.png
        @3.0x/
            JoystickKnobBackground.png
        @4.0x/
            JoystickKnobBackground.png

在此设置中，加拿大法语将使用 fr-CA 的 JoystickKnobForeground 资产、fr 的 JoystickKnobBackground 资产以及 neutral 的 JoystickBackground 资产。法国法语将同时使用 fr 资产用于 JoystickKnobForeground 和 JoystickKnobBackground，以及 neutral 资产用于 JoystickBackground。所有其他语言将对所有内容使用 neutral 资产。

从布局中引用资产

资产是在应用资产的控件的样式部分中引用的。为了引用资产，被样式化的项类型应为 “asset”，并且值应为不带 PNG 扩展名的资产文件名。例如，使用上面资产设置样式的摇杆可能配置如下：

{
  "type": "joystick",
  "styles": {
    "default": {
      "background": {
        "type": "asset",
        "value": "JoystickBackground"
      },
      "knob": {
        "faceImage": {
          "type": "asset",
          "value": "JoystickKnobForeground"
        },
        "background": {
          "type": "asset",
          "value": "JoystickKnobBackground"
        }
      }
    }
  }
}

有了这种样式，对于摇杆使用的三个资产中的每一个，Touch Adaptation Kit 将使用玩家设备的语言和 DPI 来查找布局要使用的最佳匹配资产。因此，布局不指定要使用的语言或资产比例，因为 Touch Adaptation Kit 将自动找到最佳匹配的资产。

使用带变量替换的资产

也可以使用 XGameStreamingUpdateTouchControlsStateOnClient API 在运行时更改布局所使用的资产。为此，必须在触控适配包的 context.json 文件中定义控件的潜在资产列表。 context.json：

{
    "$schema": "https://raw.githubusercontent.com/microsoft/xbox-game-streaming-tools/main/touch-adaptation-kit/schemas/context/v3.3/context.json",
    "definitions": {
      "potionButtonImages": [
        "Empty",
        "Healing",
        "Invisibility",
        "Mana"
      ]
    },
    "state": {
      "potionButtonFaceImage": "Empty"
    },
    "allowedStateValues": {
      "potionButtonFaceImage": {
        "$ref": "#/definitions/potionButtonImages"
      }
    }
  }
}

这将包的上下文设置为允许在布局中使用 Empty.png、Healing.png、Invisibility.png 或 Mana.png 中的任何一个用作药水按钮图像。当前选定的图像存储在状态变量 potionButtonFaceImage 中。按钮本身将配置为对此上下文的引用： layout.json：

{
  "type": "button",
  "styles": {
    "default": {
      "faceImage": {
        "type": "asset",
        "value": {
          "$ref": "../../context.json#/state/potionButtonFaceImage"
        }
      }
    }
  }
}

这告诉按钮使用当前存储在上下文的 potionButtonFaceImage 状态变量中的任何资产作为其面部图像。最后，当游戏想要更改此按钮当前显示的图像时，它将使用如下代码：

HRESULT ChangePotion(XGameStreamingClientId client, const char* potionName)
{
    XGameStreamingTouchControlsStateOperation updateOperations[1] = {};
    updateOperations[0].operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    updateOperations[0].path = "/potionButtonFaceImage";
    updateOperations[0].value.valueKind = XGameStreamingTouchControlsStateValueKind::String;

    // potionName is one of "Empty", "Healing", "Invisibility", "Mana"
    updateOperations[0].value.stringValue = potionName;

    return XGameStreamingUpdateTouchControlsStateOnClient(client, _countof(updateOperations), updateOperations);
}

此代码更改了存储在 potionButtonFaceImage 状态变量中的资产的名称，这将导致新选定的资产出现在任何在其样式中引用此状态的布局中。

自定义资产尺寸

下表总结了每个控件上可以应用自定义资产的元素，以及每个资产 1.0x 缩放的最大像素尺寸。

控件	可设置样式的元素	@1.0x 像素尺寸
ArcadeButton	background	60 x 60
	faceImage	60 x 60
Button	background	60 x 60
	faceImage	60 x 60
DirectionalPad	background	60 x 60
Joystick	background	120 x 120
	knob/background	60 x 60
	knob/faceImage	60 x 60
Throttle	knob/background	60 x 60
	knob/faceImage	60 x 60
Touchpad	background (renderAsButton = true)	60 x 60
	background (renderAsButton = false)	120 x 120
	faceImage	60 x 60

ArcadeButton faceImage、Button faceImage、Joystick knob faceImage、Throttle knob faceImage 和 Touchpad faceImage 资产的像素尺寸为：

缩放	像素尺寸
@1.0x	60 x 60
@1.5x	90 x 90
@2.0x	120 x 120
@3.0x	180 x 180
@4.0x	240 x 240

ArcadeButton background、Button background、DirectonalPad background、Joystick knob background、Throttle knob background 和 Touchpad（在 renderAsButton=true 时）background 资产的像素尺寸为：

缩放	像素尺寸
@1.0x	60 x 60
@1.5x	90 x 90
@2.0x	120 x 120
@3.0x	180 x 180
@4.0x	240 x 240

Joystick background 和 Touchpad（在 renderAsButton=false 时）background 资产的像素尺寸为：

缩放	像素尺寸
@1.0x	120 x 120
@1.5x	180 x 180
@2.0x	240 x 240
@3.0x	360 x 360
@4.0x	480 x 480

图像量化

构建触控适配包时，TAK CLI 将对提供的 PNG 执行量化，以减小生成的 .takx 文件的大小。虽然量化不应影响资产的外观，但仍建议验证触控布局中显示的资产与你在创建图像时所认为的外观相匹配。如果量化过程正在影响你的图像渲染方式，可以通过在构建包时向 TAK CLI 传递 --no-asset-optimization 选项来禁用它。

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

资产文件

从布局中引用资产

使用带变量替换的资产

自定义资产尺寸

图像量化

​资产文件

​从布局中引用资产

​使用带变量替换的资产

​自定义资产尺寸

​图像量化

资产文件

从布局中引用资产

使用带变量替换的资产

自定义资产尺寸

图像量化