觸摸控制

From DDraceNetwork
Revision as of 07:51, 1 January 2025 by ForgottenCat (talk | contribs) (Created page with "除此之外，根对象还有以下属性：")
Other languages:

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

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

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

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

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

默認鍵位

遊戲內默認鍵位的截圖。

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

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

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

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

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

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

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

全部按鍵預覽時的默認鍵位截圖

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

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

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

鍵位設置格式

上述提到的默認鍵位是在一個名為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": 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

Screenshot of the additional buttons in the ingame menu when touch controls are enabled.

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

Screenshot of the ingame touch controls editor user interface.

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

  1. Export the touch configuration to the clipboard.
  2. 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!
  3. Edit the configuration (see above for details about the format).
  4. 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.
  5. 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

Retrieved from "https://wiki.ddnet.org/index.php?title=Touch_controls/zh&oldid=38215"