Controles táctiles

Los controles táctiles fueron agregados al cliente DDNet en la versión 18.8, para la cual también se publicó la primera versión más reciente para Android. La versión de DDNet anterior para Android es la 9.3.1, para la cual existe un tutorial separado. Ahora solamente se considerarán los controles táctiles desde la versión 18.8 en adelante.

La interfaz de usuario se puede usar con los controles táctiles de las siguientes maneras:

Toca donde sea para mover el cursor y hacer la acción de clic izquierdo.
Toca y mantén por al menos 0,5 segundos en la misma posición para hacer la acción de clic derecho.
Usa dos dedos para para desplazarte hacia arriba y abajo en listas desplazables como el navegador de servidores y en la consola.
En Android: Usa el botón (virtual) Volver como tecla Escape para cerrar menús y demás.

Los controles táctiles pueden ser activados o desactivados con la variable de configuración cl_touch_controls, la cual por defecto es 1 en dispositivos Android y 0 en otras plataformas. Los controles táctiles deberían tambien funcionar en otras plataformas que permitan dispositivos táctiles, pero esta guía justamente fue probada en Android.

Los controles táctiles consisten en varios botones en pantalla, los cuales son mostrados dependiendo del contexto en el que se usen. Por ejemplo: los botones para el movimiento son solamente mostrados cuando se está dentro del juego.

Configuración predeterminada de los botones táctiles

Los botones para moverse a la derecha, izquierda y saltar están ordenados en forma de ⊥, similar a WASD.

Para las acciones de disparar y usar el gancho existen dos modos:

Entrada táctil directa: el ratón se mueve exactamente en donde el jugador toca la pantalla.
Joystick virtual: un botón es usado para emular un joystick, en el cual el movimiento del ratón es relativo al centro de la pantalla.

En cualquier modo, se puede usar un botón para cambiar entre las acciones activas (disparar y gancho). Mientras el joystick virtual se mantiene presionado, este botón usa la otra acción directamente en vez de cambiar a ella.

El modo de entrada táctil directa puede ser ajustado separadamente para jugar o estar en espectador para prevenir entradas táctiles accidentales al usar un 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