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 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.

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 mientras se juega. Posibles valores:
- "disabled": La entrada táctil directa no se usa mientras se juega. Esto significa que es necesario un joystick virtual.
- "action": La entrada táctil directa usa la acción activa (ver arriba).
- "aim": La entrada táctil directa solo cambia la posición de apuntado sin usar una acción. Esto implica que se necesitan botones separados para realizar las acciones.
- "fire": La entrada táctil directa siempre usa disparo.
- "hook": La entrada táctil directa siempre usa gancho.

"direct-touch-spectate": especifica el modo de entrada táctil directa mientras se está en modo espectador. Posibles valores:
- "disabled": La entrada táctil directa no se usa mientras se está en modo espectador. Esto significa que es necesario un joystick virtual.
- "aim": La entrada táctil directa se usa para la vista de espectador.

"background-color-inactive" (añadido en DDNet 19.0): especifica el color de fondo de los botones táctiles inactivos. Ver detalles sobre el formato de color más abajo.

"background-color-active" (añadido en DDNet 19.0): especifica el color de fondo de los botones táctiles activos. Ver detalles sobre el formato de color más abajo.

Formatos de color

Los colores se especifican en cadenas hexadecimales con los formatos RRGGBBAA, RRGGBB, RGBA y RGB sin ningún prefijo como #, por ejemplo: "A526C440". Si el valor de opacidad se omite, se establecerá en opacidad total por defecto.

Botones de menú del juego

Además de los controles táctiles en pantalla por separado, una segunda fila es añadida a la página principal del menú dentro del juego cuando cl_touch_controls está activado, para funciones menos utilizadas que de otro modo no serían accesibles sin un teclado:

Botones para abrir las consolas local y remota. Abrir la consola local sin los controles táctiles es útil porque ahí se mostrarán los mensajes de error si la configuración de los controles táctiles no pudo cargarse.
Botón para cerrar el menú, lo cual es más conveniente que usar el botón de retroceso virtual si no siempre está visible.
Casilla de verificación para activar o desactivar la interfaz del editor de controles táctiles (ver abajo).

Editor de controles táctiles

La interfaz de usuario para ajustar los controles táctiles se muestra sobre la pantalla principal del menú del juego cuando está activada. Por ahora, el editor de controles táctiles está limitado a funciones básicas de gestión de configuración.

Guardar la configuración en el archivo touch_controls.json dentro del directorio de configuración.
Descartar los cambios actuales recargando el archivo touch_controls.json desde el directorio de configuración.
Restaurar la configuración predeterminada recargando el archivo touch_controls.json desde el directorio de datos.
Mostrar si hay cambios no guardados.
Importar y exportar la configuración desde y hacia el portapapeles. Esta es la única forma de editar la configuración en versiones más recientes de Android, ya que no es posible modificar archivos dentro del almacenamiento de las aplicaciones.

Además, la configuración global de los controles táctiles puede ajustarse en esta interfaz de usuario:

Los modos de entrada táctil directa mientras se está en el juego y en el modo espectador (ver Formato de configuración de botones táctiles) pueden ajustarse mediante menús desplegables.

Mientras el editor de controles táctiles esté activo, todos los botones táctiles se mostrarán independientemente de sus visibilidades, para mejorar el soporte en la disposición de los botones.

Ajustando los controles

Exporta la configuración de los controles táctiles al portapapeles.
Guarda el portapapeles en un archivo para que puedas editarlo más fácilmente. ¡También deberías hacer esto para tener una copia de seguridad de tu configuración!
Edita la configuración (ve más arriba para detalles sobre el formato).
Copia la configuración editada al portapapeles e impórtala de nuevo en el cliente. Si la configuración no se pudo cargar correctamente, revisa la consola local en busca de mensajes de error relacionados con touch_controls y corrige la configuración en consecuencia. Utiliza herramientas en línea para validar y dar formato al JSON.
Guarda los cambios en el cliente cuando hayas terminado. También puedes descartar los cambios o revertir a la configuración predeterminada si cometiste un error.

Se está planeando una interfaz de usuario más conveniente para editar los controles táctiles directamente en el cliente.

Nota: También puedes editar el archivo touch_controls.json directamente en el directorio de configuración en lugar de exportar/importar desde/hacia el portapapeles, pero esto no está soportado en Android.

Ejemplos

Ejemplo de la estructura general de la configuración de los controles táctiles:

{
    "direct-touch-ingame": "action",
    "direct-touch-spectate": "aim",
    "background-color-inactive": "00000040",
	"background-color-active": "33333340",
    "touch-buttons": [
        ...
    ]
}

Ejemplo de un botón con comportamiento de "bind" que envía un mensaje al chat:

{
    "x": 500000,
    "y": 500000,
    "w": 100000,
    "h": 100000,
    "shape": "rect",
    "visibilities": [
    ],
    "behavior": {
        "type": "bind",
        "label": "Ejemplo",
        "label-type": "plain",
        "command": "echo ¡Hola mundo!"
    }
}

Ejemplo de un botón con comportamiento "predefined" para un joystick virtual que usa la acción activa:

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

Ejemplo de un botón con comportamiento "bind-toggle" que alterna entre enviar tres mensajes diferentes en el 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"
            }
        ]
    }
}

Problemas conocidos

Problema en Android: Al presionar con 3 o más dedos al mismo tiempo, se sueltan todos los dedos de inmediato.
- Solución: Esto es causado por características de tu teléfono que manejan gestos globales con múltiples dedos. Abre la aplicación de Configuración y desactiva las funciones de gestos que involucren 3 o más dedos (busca "3 dedos"). En particular, desactiva las funciones "Deslizar hacia abajo con 3 dedos para tomar una captura de pantalla", "Mantener tocado con 3 dedos para tomar una captura de pantalla" y "Deslizar hacia arriba con 3 dedos para ingresar al modo Split View".
Problema en Android: En raras ocasiones, tocar en la parte superior de alrededor del 15% de la pantalla no funciona en absoluto o funciona de manera muy inconsistente.
- Solución: No está claro qué causa esto. Debería solucionarse reiniciando la aplicación. Regresar a la pantalla de inicio también puede solucionarlo.

Detalles de implementación

Estos son detalles sobre la implementación de los controles táctiles dirigidas a desarrolladores.

Los controles táctiles dentro del juego están implementados en un componente de cliente separado llamado CTouchControls en los archivos src/game/client/components/touch_controls.cpp y src/game/client/components/touch_controls.h. Siempre que sea posible, se utilizan los binds directamente como comportamiento de los botones en lugar de usar un comportamiento predefinido para reducir la complejidad.

Cuando añadas tu propio comportamiento de botones en un cliente bifurcado, se recomienda anteponer los nombres de nuevas formas, visibilidades, comportamientos, etc., con el nombre de tu bifurcación, por ejemplo, minombre.octagon si añades una nueva forma para botones octagonales, para evitar conflictos en versiones futuras.

Para agregar soporte táctil para otros componentes del cliente ingame, como la rueda de emoticonos y el menú de espectador, usa la función CUi::UpdateTouchState como para la rueda de emoticonos y el menú de espectador. Asegúrate de que tu componente maneje KEY_ESCAPE para cerrarse, lo que también corresponde al botón Atrás en Android. Ten en cuenta que solo un componente puede usar el estado táctil en cada frame, por lo que no es posible mantener presionado un botón táctil ingame y usar otro componente, como la rueda de emoticonos, al mismo tiempo con otros dedos. En su lugar, el comportamiento táctil predefinido respectivo (por ejemplo, CSpectateTouchButtonBehavior) solo activa el componente ingame (por ejemplo, el menú de espectador) en su función OnDeactivate, pero no lo desactiva nuevamente. Activar el componente en la función OnActivate ya causaría que el dedo que activó el botón también afectara al componente activado.

Referencias

Configuración por defecto de los controles táctiles: https://github.com/ddnet/ddnet/blob/69c92a79e6bab9f9390245f518c5340222c544dc/data/touch_controls.json
Pull Request añadiendo los Controles táctiles al motor y a la interfaz de usuario: https://github.com/ddnet/ddnet/pull/8621
Pull Request añadiendo los controles táctiles Ingame: https://github.com/ddnet/ddnet/pull/8632
Pull Request añadiendo los controles táctiles de Emoticonos y Espectear: https://github.com/ddnet/ddnet/pull/8801