How to create custom touch control layout

Note

Please use this topic for questions & feedback

Limitations

• Doesn't support custom layout assets
• Cannot dynamically switch layouts based on the game's context (one layout for the entire game, unless you manually switch it)

Requirements

• Visual Studio Code
• Have Chrome/Edge or any Chromium browsers installed.
• Have an Android device with Kiwi Browser installed if you want to test on real device.
• Basic knowgledge about:
  • JSON format
  • Chrome DevTools and its Console Panel
• Get familiar with the Touch Adaptation Kit. This is the same tech that is being used to create touch control layouts in xCloud and Better xCloud. The tool isn't provided publicly so we have to create the layout manually.

How to create layout

1. Install TAK CLI and Touch Adaptation Kit Editor extension in VS Code.
2. Read Touch Adaptation Kit Editor extension's documentation to create an empty bundle and play around with the layout.
3. Use the Touch Adaptation Kit documentation to design your own layout. You can also look at other custom layouts for references.
4. One you're satisfied with the layout, go to the next section.

Here is the default layout if you need it:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/xbox-game-streaming-tools/master/touch-adaptation-kit/schemas/layout/v4.0/layout.json",
  "content": {
    "left": {
      "inner": [
        {
          "type": "joystick",
          "expand": false,
          "axis": {
            "input": "axisXY",
            "output": "leftJoystick"
          }
        }
      ],
      "outer": [
        null,
        null,
        [
          {
            "type": "directionalPad"
          }
        ],
        {
          "type": "button",
          "action": "leftThumb"
        },
        null,
        {
          "type": "button",
          "action": "leftTrigger"
        },
        {
          "type": "button",
          "action": "leftBumper"
        }
      ]
    },
    "right": {
      "inner": [
        {
          "type": "button",
          "action": "gamepadY"
        },
        {
          "type": "button",
          "action": "gamepadB"
        },
        {
          "type": "button",
          "action": "gamepadA"
        },
        {
          "type": "button",
          "action": "gamepadX"
        }
      ],
      "outer": [
        {
          "type": "button",
          "action": "rightBumper"
        },
        {
          "type": "button",
          "action": "rightTrigger"
        },
        null,
        {
          "type": "button",
          "action": "rightThumb"
        },
        [
          {
            "type": "joystick",
            "axis": {
              "input": "axisXY",
              "output": "rightJoystick"
            }
          }
        ]
      ]
    },
    "upper": {
      "right": [
        {
          "type": "button",
          "action": "menu"
        },
        {
          "type": "button",
          "action": "view"
        }
      ]
    }
  }
}

Preparations for testing on desktop

1. Open the xCloud website in Chrome/Edge/Chromium browser.

2. Open the Chrome DevTools.

3. Click on the Toggle device emulation button and set Dimensions to any device you want. I prefer iPhone SE because it has 16:9 screen ratio. Don't select Android devices or Chrome will become fullscreen every time you load a game.
   

   

4. Reload the page. This step is necessary, don't skip it.

5. Make sure the Touch controller > Availability setting is set to All games. Reload the page if needed.

   

6. Done.

Preparations for testing on Android device

1. Enable Developer mode > USB Debugging on your Android device.
2. Connect the device with your PC.
3. Open xCloud in Kiwi Browser.
4. On PC, open about:inspect in Chrome/Edge.
5. Find the xCloud row and click on "inspect fallback"
6. Done

Getting started

1. Do all the preparation steps.
2. Open Chrome DevTools, enable Toggle device emulation, reload page.
3. Load the game you want to create custom layout for. It must not having official touch support. In this guide I'll pick DOOM (1993).
   
4. Switch to Console panel in Chrome DevTools. Click on the 🚫 button to clear the console.
5. We'll pass the custom layout to the testTouchLayout() function to test it. Paste the entire content of the layout that you created in VS Code to the console, then press Enter:

testTouchLayout(
{
  "$schema": "https://raw.githubusercontent.com/microsoft/xbox-game-streaming-tools/main/touch-adaptation-kit/schemas/layout/v4.0/layout.json",
  "content": {
  ...
  }
}
)

Submit layout

1. Remove "$schema" line from the layout

2. Add "name": "Layout Name" line into the layout (Replace "Layout Name" with the real name)

3. Add "author": "Author Name" line into the layout (Replace "Author Name" with your username)

4. Fork the gh-pages branch:

5. Create two files: touch-layouts/<XBOX_TITLE_ID>.json and touch-layouts/layouts/<LAYOUT_FILE_NAME>.json

• <XBOX_TITLE_ID>.json:
  • To find the value of XBOX_TITLE_ID:
    1. Find the game on dbox.tools. Here is the page for DOOM 1993.
    2. Copy the value in Title ID row (Doom 1993 = 60A2D9F6).
    3. Convert that value into decimal and you get your XBOX_TITLE_ID value. For DOOM 1993 it's 1621285366.
  • File template:

{
  "name": "GAME NAME",
  "default_layout": "LAYOUT_ID",
  "layouts": [
    "LAYOUT_FILE_NAME"
  ]
}

• layouts/<GAME>.json:
  • File template:

{
  "schema_version": 1,
  "layouts": {
    "LAYOUT_ID": <LAYOUT_JSON>
  }
}

6. ⚠️ Use DuckDuckGo's JSON Beautifier tool (indent with 2 spaces) to beautify & validate the JSON files. Copy the result and paste it back into the layout file.

7. Create a pull request including the screenshot of the layout. Chrome/Edge has a built-in screenshot feature:

8. Done! That's the basic of it. I'll update with more details later.