觸摸控制

觸摸控制從DDNet客戶端的18.8版本後已經可用，這也是近期首個發布的DDNet安卓版。早期的安卓版DDNet為9.3.1版本，此版本有一個單獨的教程。接下來我們會只考慮18.8以及更新版本的觸摸控制。

用戶界面可通過觸摸控制進行的操作如下：

在任意地方觸摸可移動光標或進行一次滑鼠左鍵點擊。
在幾乎一個地點按住至少0.5秒可進行一次滑鼠右鍵點擊。
用兩根手指可向上或下滾動可滾動條，例如伺服器瀏覽器和控制台。
在安卓上：用(虛擬)返回鍵當做退出鍵，可關閉菜單等。

在遊戲中的觸摸控制可以用配置變量cl_touch_controls來開啟/關閉，此變量在安卓默認為1，在其他平台則是0。觸摸控制應該在其他支持觸摸功能的平台上也能使用，但是此教程主要在安卓上進行的測試。

遊戲內觸摸控制包含多種在屏幕上的按鍵。不同按鍵僅會在特定時候顯示，取決於其內容。例如移動鍵僅會在遊玩過程中顯示。

默認鍵位

左，右移動鍵以及跳躍鍵的布局類似於⊥的樣子，和WASD控制類似。

對於開火和出鉤動作，這裡設置了兩種模式：

直接的點擊輸入：準星會直接移動至玩家點擊屏幕的位置。
虛擬搖杆：一個按鍵會模擬搖杆，可以使準星相對於屏幕中心移動。

在兩個模式中，一個按鍵可用於切換當前啟用的動作(開火和出鉤)。當虛擬搖杆被按下時，該按鍵可以直接使用未被啟用的動作而不是切換。

直接點擊輸入模式可以依據在遊戲內/旁觀中分別調整功能，以此在使用搖杆時避免不必要的點擊輸入。

旁觀時，直接點擊輸入可用於移動地圖，類似於在圖片/地圖預覽器。虛擬搖杆也可用於在旁觀時移動地圖。

兩個獨立的按鈕可分別用於切換至上一個或下一個武器。

一個漢堡包菜單按鈕☰可用於切換更少使用按鍵的可見性，包括顯示記分板，顯示錶情選擇器，顯示旁觀菜單，打開隊伍和隊伍內聊天，投票贊成/反對，和縮放按鍵。長按漢堡包菜單按鈕會打開遊戲內菜單。

當分身被連接時，一個用於切換分身和本體的按鍵會顯示。

表情選擇器和旁觀菜單可被相關按鍵打開，之後可通過在面板外點擊或使用返回鍵關閉，另外僅當相關按鈕被按下時才打開面板這種設置目前而言不可行，至少這種設置對於旁觀菜單而言不便利。

鍵位設置格式

上述提到的默認鍵位是在一個名為touch_controls.json的文件中被加載，該文件位於data目錄因此無法被修改。該鍵位可通過在配置目錄中創建一個名為touch_controls.json來修改。

鍵位配置文件是一個JSON格式的文本文件。推薦先學習JSON的基本格式來更好的理解以下教程。配置文件必須是一個有效的JSON文件。JSON格式的教程和檢查工具可在網絡上找到。JSON文件的結構如下。

The root element in the JSON file must be an object. The attribute "touch-buttons" of the root object specifies an array of touch button objects. Each touch button object has the following adjustable properties:

Position and size (attributes "x", "y", "w", "h"): the X/Y position and width/height are integers on a 1,000,000² grid. These unit grid values are converted to screen grid values at runtime in relation to the size and aspect ratio of the screen. This means buttons may appear stretched if the resolution is changed, but it allows us to provide a reasonable default for slightly different aspect ratios.
Shape (attribute "shape"): determines the shape of the button being rendered.
- "rect": rectangle shape.
- "circle": circle shape. The button size will automatically be adjusted so that width and height are identical.
Visibility (attribute "visibilities"): an array of predefined visibility classes can be selected and the button is only shown if all conditions are satisfied. An empty array means that the button is always shown. The following visibility classes are defined:
- "ingame": player is ingame, i.e. not spectating.
- "extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4", "extra-menu-5": the extra menu with the given number is activated.
- "zoom-allowed": zoom is allowed on this server.
- "vote-active": a vote is currently active.
- "dummy-allowed": dummy is allowed on this server.
- "dummy-connected": dummy is currently connected.
- "rcon-authed": player is currently authed in rcon.
- "demo-player": demo player is currently active.
- All visibility classes can be inverted by prefixing them with -, e.g. "-ingame" is satisfied when the player is not ingame, i.e. spectating.
Behavior (attribute "behavior"): an object which describes the behavior of this touch button when it is activated/deactivated as well as its label. The attribute "type" is used to differentiate which type of behavior is used. The behavior is either predefined (hard-coded) or based on generic console commands (like binds). Predefined behavior is only used where necessary, all other buttons are represented as generic binds.
- Predefined behavior (attribute "type" set to "predefined"): The attribute "id" is set to a fixed string value which determines the specific predefined behavior. The following predefined behaviors can be used:
  - "ingame-menu": Opens the ingame menu immediately when released.
  - "extra-menu": The extra menu button which toggles visibility of buttons with "extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4" and "extra-menu-5" visibilities. Also opens the ingame menu on long press.
    - The attribute "number" specifies an integer between 1 and 5 to associate this button with the respective visibilities "extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4", "extra-menu-5".
  - "emoticon": Opens the emoticon selector (this does not work with binds).
  - "spectate": Opens the spectator menu (this does not work with binds).
  - "swap-action": Swaps the active action (fire and hook) for direct touch input and virtual joysticks.
  - "use-action": Uses the active action with the current aiming position.
  - "joystick-action": Virtual joystick which uses the active action.
  - "joystick-aim": Virtual joystick which only aims without using an action.
  - "joystick-fire": Virtual joystick which always uses fire.
  - "joystick-hook": Virtual joystick which always uses hook.
- Bind behavior (attribute "type" set to "bind"). Buttons with this behavior execute console commands like regular key binds.
  - The attribute "label" specifies as a string the label of the button.
  - The attribute "label-type" specifies as a string the type of the label of the button, i.e. how the attribute "label" is interpreted:
    - "plain": Label is used as is.
    - "localized": Label is localized. Only usable for the default buttons for which there are translations available.
    - "icon": Icon font is used for the label. Icons must be encoded in UTF-16 using \uXXXX, e.g. \uf3ce for the mobile phone icon which has unicode f3ce. Note that the icon must be available in the icon font that comes with DDNet, Font Awesome Free.
  - The attribute "command" specifies as a string the command to execute in the console like a bind when this button is used, e.g. "+fire" for a button that uses the fire action.
- Bind toggle behavior (attribute type set to "bind-toggle"). Buttons with this behavior cycle between executing one of two or more specified commands.
  - The attribute "commands" specifies an array of two or more commands in the order in which they are shown and executed. Each command is an object with the attributes "label", "label-type" and "command" which are defined the same as for the bind behavior described above. At least two command objects must be specified in the array.

The root object additionally has the following attributes:

"direct-touch-ingame": specifies the mode of direct touch input while ingame. Possible values:
- "disabled": Direct touch input is not used while ingame. This means a virtual joystick is necessary.
- "action": Direct touch input uses the active action (see above).
- "aim": Direct touch input only changes the aiming position without using an action. This means separate buttons for using the actions are necessary.
- "fire": Direct touch input always uses fire.
- "hook": Direct touch input always uses hook.
"direct-touch-spectate": specifies the mode of direct touch input while spectating. Possible values:
- "disabled": Direct touch input is not used while spectating. This means a virtual joystick is necessary.
- "aim": Direct touch input is used for spectating.

Ingame menu buttons

In addition to the separate on-screen touch controls, a second row is added to the main page of the ingame menu when cl_touch_controls is enabled for less frequently used functions which are otherwise not usable without a keyboard:

Buttons to open the local and remote consoles. Opening the local console without the touch controls is useful because error messages would be shown there if the touch controls configuration could not be loaded.
Button to close the menu, which is more convenient than using the virtual back button if it's not always shown.
Checkbox for toggling the touch controls editor UI (see below).

Ingame touch controls editor

The user interface to adjust the touch controls is rendered over the main screen of the ingame menu when enabled. For now, the touch controls editor is limited to basic configuration management functions.

Saving the configuration to the touch_controls.json file in the config directory.
Discarding the current changes by reloading the touch_controls.json file from the config directory.
Restoring the default configuration by reloading the touch_controls.json file from the data directory.
Displaying whether there are unsaved changes.
Importing and exporting the configuration from and to the clipboard. This is the only way to edit the configuration on newer Android versions, as editing files within apps' storage is not possible anymore.

Furthermore, the global touch controls settings can be adjusted in this UI:

The direct touch input modes while ingame and spectating (see Touch button configuration format) can be adjusted using dropdown menus.

While the touch controls editor is active, all touch buttons are shown regardless of their visibilities, to better support arranging the buttons.

Adjusting the controls

Export the touch configuration to the clipboard.
Save the clipboard to a file so you can more easily edit it. You should also do this to have a backup of your configuration!
Edit the configuration (see above for details about the format).
Copy the edited configuration to the clipboard and import it in the client again. If the configuration could not be loaded successfully, check the local console for error messages containing touch_controls and fix the configuration accordingly. Use online tools for JSON validation and formatting.
Save the changes in the client when you are done. You can also discard your changes or revert to the default if you messed up.

A more convenient user interface to edit the touch controls directly in the client is planned.

Note: You can also edit the file touch_controls.json in the config directory directly instead of exporting/importing to/from the clipboard, but this is not supported on Android.

Examples

Example for the overall structure of the touch configuration:

{
    "direct-touch-ingame": "action",
    "direct-touch-spectate": "aim",
    "touch-buttons": [
        ...
    ]
}

Example button with "bind" behavior that echos a message in chat:

{
    "x": 500000,
    "y": 500000,
    "w": 100000,
    "h": 100000,
    "shape": "rect",
    "visibilities": [
    ],
    "behavior": {
        "type": "bind",
        "label": "Example",
        "label-type": "plain",
        "command": "echo Hello world!"
    }
}

Example button with "predefined" behavior for a virtual joystick that uses the active action:

{
    "x": 755000,
    "y": 580000,
    "w": 225000,
    "h": 400000,
    "shape": "circle",
    "visibilities": [
        "ingame"
    ],
    "behavior": {
        "type": "predefined",
        "id": "joystick-action"
    }
}

Example button with "bind-toggle" behavior that switches between echoing three different messages in chat:

{
    "x": 600000,
    "y": 200000,
    "w": 100000,
    "h": 100000,
    "shape": "rect",
    "visibilities": [
    ],
    "behavior": {
        "type": "bind-toggle",
        "commands": [
            {
                "label": "Echo 1",
                "label-type": "plain",
                "command": "echo 1"
            },
            {
                "label": "Echo 2",
                "label-type": "plain",
                "command": "echo 2"
            },
            {
                "label": "Echo 3",
                "label-type": "plain",
                "command": "echo 3"
            }
        ]
    }
}

Known issues

Problem on Android: Pressing down 3 or more fingers at the same times causes all fingers to be released immediately.
- Solution: This is caused by features of your phone that handle global gestures with multiple fingers. Open the Settings app and disable gesture features that involve 3 or more fingers (search for "3 fingers"). In particular, disable the "Swipe down with 3 fingers to take screenshot", "Touch and hold with 3 fingers to take screenshot" and "Swipe up with 3 fingers to enter Split View" features.
Problem on Android: Rarely, touching in the top around 15% of the screen does not work at all or very inconsistently.
- Solution: It is unclear what causes this. It should be fixed by restarting the app. Going back to the home screen may also fix it.

Implementation details

These are details about the implementation of the touch controls intended for developers.

The ingame touch controls are implemented in a separate client component CTouchControls in the files src/game/client/components/touch_controls.cpp and src/game/client/components/touch_controls.h. Whenever possible, binds are used directly as button behavior instead of using predefined behavior to reduce complexity.

When adding your own button behavior in a forked client it is recommended to prefix names of new shape, visibility, behavior etc. with the name of your fork, e.g. myfork.octagon if you add a new shape for octogonal buttons, to prevent conflicts in future versions.

To add touch support for other ingame client components like the emoticon wheel and spectator menu, use the CUi::UpdateTouchState function like for the emoticon wheel and spectator menu. Ensure that your component handles KEY_ESCAPE to close itself, which also corresponds to the Back-button on Android. Note that only one component may use the touch state in each frame, so it is not possible to hold an ingame touch button and use another component like the emoticon wheel at the same time with other fingers. Instead, the respective predefined touch button behavior (e.g. CSpectateTouchButtonBehavior) only activates the ingame component (e.g. the spectator menu) in its OnDeactivate function but does not deactivate it again. Activating the component in the OnActivate function already would cause the finger that activated the button to also affect the activated component.

References

Default touch button configuration: https://github.com/ddnet/ddnet/blob/84b1c3c49c8d97a6911da34424d2023879ccdaf8/data/touch_controls.json
Pull Request adding Touch controls to engine and UI: https://github.com/ddnet/ddnet/pull/8621
Pull Request adding Ingame touch controls: https://github.com/ddnet/ddnet/pull/8632
Pull Request adding Emoticon and Spectate touch controls: https://github.com/ddnet/ddnet/pull/8801