Touch controls/es

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

Captura de pantalla de los controles táctiles predeterminados dentro del juego.

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:

1. Entrada táctil directa: el ratón se mueve exactamente en donde el jugador toca la pantalla.
2. 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 cualquiera de los modos, se utiliza un botón para alternar entre las acciones activas (disparar y enganchar). Mientras se mantiene presionado el joystick virtual, este botón ejecuta directamente la otra acción en lugar de cambiarla.

El modo de entrada táctil directa puede ajustarse por separado para jugar y observar, evitando así entradas táctiles accidentales al usar un joystick.

Al observar, se utiliza la entrada táctil directa para desplazarse por el mapa directamente, como en un visor de imágenes o mapas. También se pueden usar los joysticks virtuales para desplazarse por el mapa mientras observas.

Dos botones separados son mostrados para cambiar al arma siguiente o anterior.

Captura de pantalla de los controles táctiles predeterminados en el juego, con todos los botones visibles.

Se utiliza un botón de menú tipo hamburguesa ☰ para alternar la visibilidad de botones de menor uso. Esto incluye botones para mostrar la tabla de puntuación, el selector de emoticonos, el menú de espectador, abrir el chat general y el de equipo, votar sí/no y hacer zoom. Mantener presionado el botón tipo hamburguesa abrirá el menú del juego.

Cuando se contecta el dummy, se muestra un botón para cambiar entre dummys.

El selector de emoticonos y el menú de espectador se activan con sus respectivos botones y pueden ser desactivados al tocar fuera de ellos o usando el boton de volver. Actualmente, alternarlos mientras se mantiene presionado el botón táctil en el juego no es factible y resulta poco práctico, al menos en el caso del menú de espectadores.

Formato de configuración de botones táctiles

La disposición predeterminada de los botones descrita anteriormente se carga desde el archivo touch_controls.json en el directorio data, el cual no debe ser modificado. Esta disposición puede ser sobrescrita creando un archivo touch_controls.json en el directorio de configuración.

La configuración de los botones táctiles es un archivo de texto en formato JSON. Se recomienda aprender primero los conceptos básicos del formato JSON para comprender la siguiente guía. La configuración debe ser un archivo JSON válido. Existen guías y herramientas de validación para el formato JSON disponibles en internet. La estructura del archivo JSON se describe a continuación.

El elemento raíz en el archivo JSON debe ser un objeto. El atributo "touch-buttons" del objeto raíz especifica un arreglo de objetos de botones táctiles. Cada objeto de botón táctil tiene las siguientes propiedades ajustables:

• Posición y tamaño (atributos "x", "y", "w", "h"): La posición X/Y y el ancho/alto son enteros en una cuadrícula de 1,000,000². Estos valores de la cuadrícula de unidades se convierten en valores de la cuadrícula de pantalla en tiempo de ejecución, en relación con el tamaño y la relación de aspecto de la pantalla. Esto significa que los botones pueden aparecer estirados si se cambia la resolución, pero nos permite proporcionar un valor predeterminado razonable para relaciones de aspecto ligeramente diferentes.
• Forma (attribute "shape"): Determina la forma del botón que se está renderizando.
  • "rect": Forma rectangular.
  • "circle": Forma circular. El tamaño del botón será ajustado automáticamente para que el ancho y alto sean idénticos.
• Visibilidad (atributo "visibilities"): Un arreglo de clases de visibilidad predefinidas puede ser seleccionado y el botón es mostrado si se cumplen todas las condiciones. Un arreglo vacío significa que el botón siempre se mostrará. Se definen las siguientes clases de visibilidad:
  • "ingame": El jugador está jugando. Es decir, no está en espectador.
  • "extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4", "extra-menu-5": Se activa el menú adicional con el número dado.
  • "zoom-allowed": El zoom está permitido en el servidor.
  • "vote-active": Una votación se encuentra activa.
  • "dummy-allowed": El dummy está permitido en el servidor.
  • "dummy-connected": El dummy está conectado actualmente.
  • "rcon-authed": El jugador está autenticado en rcon.
  • "demo-player": El reproductor de demo está activo.
  • Todas las clases de visibilidad pueden ser invertidas anteponiéndoles un -, por ejemplo, "-ingame" se cumple cuando el jugador no está en el juego, es decir, está en espectador.
• Comportamiento (atributo "behavior"): Un objeto que describe el comportamiento de este botón cuando se activa/desactiva, así como su etiqueta. El atributo "type" se utiliza para diferenciar qué tipo de comportamiento se emplea. El comportamiento es predefinido (hard-coded) o basado en comandos genéricos de consola (como los binds). El comportamiento predefinido solo se usa cuando es necesario, todos los demás botones se representan como binds genéricos.
  • Comportamiento predefinido (atributo "type" establecido en "predefined"): El atributo "id" se establece con un valor de cadena fijo que determina el comportamiento predefinido específico. Los siguientes comportamientos predefinidos pueden ser utilizados:
    • "ingame-menu": Abre el menú del juego inmediatamente cuando se suelta.
    • "extra-menu": El botón de menú adicional que alterna la visibilidad de los botones con las visibilidades "extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4" y "extra-menu-5". También abre el menú del juego al mantener presionado.
      • El atributo "number" especifica un entero entre 1 y 5 para asociar este botón con las visibilidades respectivas "extra-menu", "extra-menu-2", "extra-menu-3", "extra-menu-4", "extra-menu-5".
    • "emoticon": Abre el selector de emoticonos (esto no funciona con un bind).
    • "spectate": Abre el menú de espectador (esto no funciona con un bind).
    • "swap-action": Intercambia la acción activa (disparar y enganchar) por entrada táctil directa y joysticks virtuales.
    • "use-action": Usa la acción activa con la posición de puntería actual.
    • "joystick-action": Joystick virtual que usa la acción activa.
    • "joystick-aim": Joystick virtual que solo apunta sin utilizar una acción.
    • "joystick-fire": Joystick virtual que siempre utiliza disparar.
    • "joystick-hook": Joystick virtual que siempre utiliza enganchar.
  • Comportamiento de bind (atributo "type" establecido en "bind"). Los botonoes con este comportamiento ejecutan comandos de consola como un bind normal.
    • El atributo "label" especifica como una cadena la etiqueta del botón.
    • El atributo "label-type" especifica como una cadena el tipo de la etiqueta del botón, es decir, cómo el atributo "label" es interpretado:
      • "plain": La etiqueta se utiliza tal cual.
      • "localized": La etiqueta está localizada. Solo es utilizable para los botones predeterminados para los cuales hay traducciones disponibles.
      • "icon": Se utiliza una fuente de iconos para la etiqueta. Los iconos deben estar codificados en UTF-16 usando \uXXXX, por ejemplo, \uf3ce para el icono de teléfono móvil, cuyo código Unicode es f3ce. Ten en cuenta que el icono debe estar disponible en la fuente de iconos que viene con DDNet, Font Awesome Free.
    • El atributo "command" Especifica como una cadena el comando a ejecutar en la consola como un bind cuando se utiliza este botón, por ejemplo,"+fire" para un botón que utiliza la acción de disparar.
  • Comportamiento de alternar binds (atributo type establecido en "bind-toggle"). Los botonoes con este comportamiento alternan la ejecución de uno entre dos o más comandos especificados.
    • El atributo "commands" especifica un arreglo de dos o más comandos en el orden en el que se muestran y se ejecutan. Cada comando es un objeto con los atributos "label", "label-type" y "command", los cuales se definen de la misma manera que el comportamiento de binds descrito anteriormente. Al menos dos objetos de comandos deben ser especificados en el arreglo.

Adicionalmente, el objeto raíz tiene los siguientes atributos:

• "direct-touch-ingame": Especifica el modo de entrada táctil directa dentro del juego. Posibles valores:
  • "disabled": La entrada táctil directa no es usada dentro del juego. Esto quiere decir que un joystick virtual es necesario.
  • "action": La entrada táctil directa utiliza la acción activa (ver más arriba).
  • "aim": La entrada táctil directa solamente cambia la posición de apuntado sin ninguna otra acción. Esto significa que se necesitarían botones separados para utilizar acciones.
  • "fire": La entrada táctil directa siempre utiliza disparar.
  • "hook": La entrada táctil directa siempre utiliza enganchar.
• "direct-touch-spectate": Especifica el modo de entrada táctil directa al observar. Posibles valores:
  • "disabled": La entrada táctil directa no es usada al observar. Esto quiere decir que un joystick virtual es necesario.
  • "aim": La entrada táctil directa se utiliza para observar.

Botones de menú del juego

Captura de pantalla de los botones adicionales del menú del juego cuando los controles táctiles están activados.

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

• 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