Touch controls: Difference between revisions

Latest revision as of 08:19, 24 December 2024

Touch controls are available in the DDNet client since version 18.8, which also marks the first recent release of the client for Android. The previous version for Android is DDNet 9.3.1 for which a separate tutorial exists. In the following we will only consider the touch controls as of versions 18.8 and newer.

The user interface can be used with touch controls as follows:

Touch anywhere to move the cursor and perform a left click.
Touch and hold for at least 0.5 seconds on roughly the same position to perform a right click.
Use two fingers to scroll up and down in scrollable lists like the server browser and in the console.
On Android: Use the (virtual) Back button like the Escape key to close menus etc.

The ingame touch controls can be enabled/disabled with the config variable cl_touch_controls, which defaults to 1 on Android and 0 on other platforms. Touch controls should also work on other platforms that support touch devices, but this guide has primarily been tested on Android.

The ingame touch controls consist of various on-screen touch buttons. The different buttons are only shown when they are usable depending on the context, e.g. buttons for movement are only shown when ingame.

Default touch button configuration

Movement buttons for left, right and jump actions are arranged in a ⊥-pattern similar to WASD controls.

For the fire and hook action, two modes are implemented:

Direct touch input: the mouse is moved exactly where the player touches on the screen.
Virtual joystick: a button is used to emulate a joystick, which moves the mouse relative to the center of the screen.

In either mode, a button is used to switch between the active actions (fire and hook). While the virtual joystick is being held down, this button uses the other action directly instead of switching it.

The direct touch input mode can be adjusted separately for ingame/spectating, to prevent accidental direct touch input when using a joystick.

When spectating, direct touch input is used to allow panning the map directly like in an image/map viewer. Virtual joysticks can also be used to pan the map while spectating.

Two separate buttons are shown to switch to the previous and next weapons.

A hamburger menu button ☰ is used to toggle the visibility of lesser used touch buttons. This includes buttons for showing the scoreboard, showing the emoticon selector, showing the spectator menu, opening team and team chat, voting yes/no, and zooming. Long pressing the hamburger menu button will open the ingame menu.

When the dummy is connected, a button for swapping between main and dummy is shown.

The emoticon selector and spectator menu are activated with the respective touch buttons and can be deactivated by touching outside of them or by using the back-button, as toggling them while the ingame touch button is pressed down is currently not feasible and also inconvenient at least for using the spectator menu.

Touch button configuration format

The default button layout described above is loaded from the file touch_controls.json in the data directory which should not be modified. This layout can be overridden by creating a file touch_controls.json in the config directory.

The touch button configuration is a text file in JSON format. It is recommended to first learn the basics of the JSON format to understand the following guide. The configuration must be a valid JSON file. Guides and validation tools for the JSON format are available on the internet. The structure of the JSON file is described in the following.

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