觸摸控制

觸摸控制從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文件從而將鍵位初始化。
用於提醒當前設置未被保存。
從剪貼板導入設置，或將設置導出至剪貼板。在較新的安卓版本中這是修改鍵位的唯一方法，因為無法直接修改應用的數據。

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

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

當鍵位編輯器被打開時，所有按鍵都會無條件顯示，從而讓玩家更好地排列按鍵。

調整鍵位

導出當前鍵位至剪貼板。
將剪貼板內容粘貼至一個文件來修改它。同時你也應該給你的鍵位設置備份！
修改鍵位設置(關於相關格式見上)。
複製所有內容至剪貼板，然後在客戶端內導入。若導入失敗，在本地控制台內找到包含touch_controls的錯誤消息，並更正錯誤。用在線工具可更正JSON文本的錯誤和格式化。
更改完成後在客戶端中保存你的設置。你也可撤銷更改或者初始化鍵位如果你搞砸了。

一個可在客戶端內直接修改鍵位的界面在計劃中。

註：你也可直接更改配置目錄中的touch_controls.json文件來修改鍵位，而不是導出/導入到剪貼板，但在安卓該做法不可行。

示例

Example for the overall structure of the touch configuration:

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

示例按鈕，帶有"bind"的行為，會在對話框返回一條消息：

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

示例按鈕，帶有"predefined"的行為，是一個會執行當前被激活的行為的虛擬搖杆：

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

示例按鈕，帶有"bind-toggle"的行為，會在對話框循環返回三條不同的消息：

{
    "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"
            }
        ]
    }
}

已知的問題

安卓的問題：同時按下三根手指會導致所有手指被立即同時鬆開。
- 解決方法：原因是你手機自帶的全局多指手勢動作(設置裡面搜"三指")。具體地，關閉"三指下滑截屏"，"三指長按截屏"，"三指上滑進入菜單"功能。
安卓的問題：有時候點擊屏幕頂端15%位置會無響應或響應不連續。
- 解決方法：目前不清楚原因。一般可以重啟應用，返回手機主界面也可能可以修復該問題。

實現細則

以下為實現觸摸控制的細節，為開發者準備。

遊戲內觸摸控制在單獨的客戶端組件CTouchControls中實現，該組件位於src/game/client/components/touch_controls.cpp和src/game/client/components/touch_concontrol.h文件中。儘量直接使用綁定作為按鈕的行為而不是預定義行為，從而降低複雜度。


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