觸摸控制

觸摸控制從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文件的結構如下。

JSON文件的根元素必須是一個對象。該對象的屬性"touch-buttons"可定義一系列按鍵的對象。每一個按鍵對象有以下可調節的性質：

位置和大小 (屬性"x", "y", "w", "h")：橫/縱坐標和寬/高數據為在單位長度為1000000²的表格上的整數。這些單位表格數據會在遊戲內依據屏幕大小和縱橫比轉換為屏幕表格數據。這意味着當解像度改變時一些按鍵可能會表現得被伸展，但這也使我們對於不同的屏幕縱橫比可提供一個合理的默認值
形狀 (屬性"shape")：決定顯示出來的按鍵形狀。
- "rect"：方形。
- "circle"：圓形。該按鍵大小會被自動調整，從而使寬度和高度一致。
可見度 (屬性"visibilities")：一系列預置的可見度設置可供選擇，且僅當所有情況都滿足時該按鍵才會顯示。若可見度置空則代表該按鍵總是顯示。預置有以下設置：
- "ingame"：玩家在遊戲中，即沒有在旁觀。
- "extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4", "extra-menu-5": 給定數字對應的附加菜單處於打開狀態。
- "zoom-allowed": 該伺服器允許縮放。
- "vote-active": 正在進行投票。
- "dummy-allowed": 該伺服器允許分身。
- "dummy-connected": 分身已經被連接。
- "rcon-authed": 玩家登錄了管理員賬號。
- "demo-player": 正位於錄像播放器。
- 所有可見度都可以在前面添加-來實現反轉。例如："-ingame"僅在玩家未處於遊戲中時滿足，即旁觀中。
行為 (屬性"behavior")：一個定義此按鍵按下/鬆開時執行的動作的對象，也包括其標籤。屬性"type"用於區分使用的行為種類。行為種類只能是預設(硬編碼的)，或者基於通用的控制台指令(類似於綁定)。預設的行為僅在需要時才使用，除此之外所有按鍵為通用綁定。
- 預設行為 (屬性"type"被設置為"predefined")：屬性"id"被設置為一個固定的字符串，以此確認使用的預設行為。以下為可用的預設行為：
  - "ingame-menu": 鬆開該按鈕時直接打開遊戲菜單。
  - "extra-menu": 附加菜單按鈕，切換帶有"extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4"和"extra-menu-5"可見度的按鈕的可見度。按住一段時間後鬆手則會打開遊戲菜單。
    - 給屬性"number"定義一個在1至5之間的整數即可對應相應的可見度"extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4", "extra-menu-5"。
  - "emoticon": 打開表情選擇器(此功能無法通過綁定使用)。
  - "spectate": 打開旁觀菜單(此功能無法通過綁定使用)。
  - "swap-action"：切換當前激活的由直接點擊和虛擬搖杆執行的動作(開火和出鈎)。
  - "use-action"：以當前瞄準角度執行激活的動作。
  - "joystick-action"：使用當前激活動作的虛擬搖杆。
  - "joystick-aim"：僅提供瞄準的虛擬搖杆，不會執行其他動作。
  - "joystick-fire"：總是會執行開火的虛擬搖杆。
  - "joystick-hook": 總是會執行出鈎的虛擬搖杆。
- 綁定行為(屬性"type"設置為"bind")。帶此行為的按鍵會執行控制台命令，和常規綁定類似。
  - 屬性"label"定義一個字符串作為該按鍵的標籤。
  - 屬性"label-type"被定義為一個字符串來決定該按鍵的標籤種類，即屬性"label"的處理方法：
    - "plain": 該標籤會被直接使用，不會做出任何改變。
    - "localized": 標籤會被自動翻譯。僅在有對應翻譯時可用。
    - "icon": 圖標字體被用於該標籤。圖標必須為UTF-16編碼，使用\uXXXX。例如\uf3ce為手機圖標，Unicode為f3ce。注意該圖標必須在Font Awesome Free可用。
  - 屬性"command"被定義為一個可以在控制台運行的指令類型字符串，類似於綁定。例如"+fire"為開火動作。
- 綁定切換行為(屬性type設置為"bind-toggle")。帶此行為的按鍵會在兩個及以上的指令之間循環觸發。
  - 屬性"commands"定義了兩個及以上的指令，依據先後排列順序依次觸發。每個指令為一個帶屬性"label", "label-type"和"command"的對象，與上述綁定行為的定義一致。在該組中必須至少定義兩個指令對象。

除此之外，根對象還有以下屬性：

"direct-touch-ingame": 定義在遊戲中直接點擊所執行的動作。可用的值有：
- "disabled"：遊戲中直接點擊不會執行任何動作。這意味着需要使用虛擬搖杆。
- "action"：直接點擊會使用當前被激活的動作(見上)。
- "aim"：直接點擊僅會改變瞄準角度，不會執行其他動作。這意味着你需要其他按鈕來開火或出鈎。
- "fire"：直接點擊總是會開火。
- "hook"：直接點擊總是會出鈎。
"direct-touch-spectate"：定義在旁觀時直接點擊所執行的動作。可用的值有：
- "disabled"：旁觀時直接點擊不會執行任何動作。這意味着需要使用虛擬搖杆。
- "aim"：直接點擊可用於旁觀。

遊戲內菜單

除了屏幕上的觸摸控制，當cl_touch_controls被開啟時，在遊戲內菜單會出現第二行不太常用，但沒有鍵盤則無法使用的功能：

開啟本地和遠程控制台的按鍵。不用自定義按鍵打開控制台可以在鍵位導入失敗時便捷地查看控制台內的錯誤信息。
關閉菜單的按鍵，在虛擬返回鍵未顯示時使關閉菜單更方便。
打開鍵位編輯器的選項(見下)。

鍵位編輯器

鍵位編輯器在被啟用時會顯示在遊戲內菜單的主屏幕上。該編輯器目前只有最基本的鍵位編輯功能。

保存當前設置至配置目錄中的touch_controls.json文件。
取消當前設置，並加載配置目錄中的touch_controls.json文件。
加載數據目錄中的touch_controls.json文件從而將鍵位初始化。
用於提醒當前設置未被保存。
從剪貼板導入設置，或將設置導出至剪貼板。在較新的安卓版本中這是修改鍵位的唯一方法，因為無法直接修改應用的數據。

同時，全局的觸摸控制也可以在該界面被修改：

遊戲中和旁觀時的直接點擊輸入(見鍵位設置格式)可以用下拉菜單調整。

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