Touch controls/ru: Difference between revisions

Latest revision as of 14:23, 15 June 2025

Сенсорные элементы управления доступны в DDNet клиенте начиная с версии 18.8, который также подмечает первый недавний релиз клиента для Android. Предыдущая версия для Android это DDNet 9.3.1 для которого существует отдельный туториал. В текущем туториале мы затронем сенсорные элементы управления для версий 18.8 и выше.

Пользовательский интерфейс может быть использован с сенсорными элементами управления следующим образом:

Коснитесь в любом месте, чтобы переместить курсор и нажать ЛКМ.
Коснитесь и удерживайте не менее 0.5 секунд примерно в том же месте, чтобы нажать ПКМ.
Используйте два пальца, чтобы листать вверх и вниз прокручиваемые списки, например: браузер серверов и консоль.
На Android: Используйте (виртуальную) кнопку Назад как клавишу Escape, чтобы закрыть меню и т.д.

Внутриигровые сенсорные элементы управления могут включаться/выключаться с помощью config variable cl_touch_controls, который по умолчанию имеет значение 1 на Android и 0 на других платформах. Сенсорные элементы управления также работают на других платформах, которые поддерживают сенсорные устройства, но этот гайд в основном тестировался на Android.

Внутриигровые сенсорные элементы управления состоят из разнообразных кнопок, отображающихся на экране. Другие кнопки показываются только когда они могут использоваться в зависимости от случая, например кнопки для движения отображаются только в игре.

Конфигурация сенсорных элементов управления по умолчанию

Кнопки перемещения влево, вправо и прыжка расположены в ⊥-образном порядке, похожим на WASD управление.

Для выстрела и хука реализовано два способа:

Прямой сенсорный ввод: мышь перемещается именно туда, куда игрок прикасается на экране.
Виртуальный джойстик: кнопка, используемая для эмуляции джойстика, которая перемещает мышь относительно центра экрана.

В другом режиме, кнопка используется для переключения между активными действиями (выстрел и хук). Когда виртуальный джойстик удерживается, эта кнопка использует другое действо напрямую, вместо переключения его.

Режим прямого сенсорного ввода может быть настроен отдельно для игры/наблюдения, чтобы предотвратить случайный прямой сенсорный ввод при использовании джойстика.

Во время наблюдения, прямой сенсорный ввод используется для панорамирования карты, например как на картинке и в просмотре карты. Виртуальные джойстики могут также быть использованы для панорамирования карты во время наблюдения.

Для перехода к предыдущему и следующему оружию отображаются две отдельные кнопки.

Кнопка меню в форме гамбургера ☰ используется для переключения видимости менее используемых кнопок. Сюда входят кнопки для отображения табло, выбора эмоций, меню наблюдателя, открытия чата и командного чата, голосования да/нет, и масштабирования. Длительное нажатие на кнопку меню в форме гамбургера откроет внутриигровое меню.

Когда дамми подключен, кнопка переключения между основным игроком и дамми отображается.

Выбор эмоций и меню наблюдателя активируются с соответствующими кнопками сенсорного управления и могут быть деактивированы нажатием за их пределами или используя кнопку Назад, поскольку переключение между ними в игре при зажатой кнопкой сенсорного управления в данный момент невозможно, а также неудобно, по крайней мере для использования меню наблюдателя.

Формат конфигурации сенсорного управления

По умолчанию расположение кнопок описанное выше загружается из файла touch_controls.json в папке in the data который не должен быть изменен.

Конфигурация сенсорного управления представляет собой текстовый файл в формате JSON. Рекомендуется для начала изучить основу формата JSON, чтобы понять данное руководство. Конфигурация должна быть корректным JSON файлом. Руководства и инструменты проверки JSON формата доступны в интернете. Структура JSON файла описана ниже.

Корневым элементом в JSON файле должен быть объект. Атрибут "touch-buttons" корневого объекта определяет массив объектов сенсорного управления. Каждый объект сенсорного управления имеет следующие настраиваемые свойства:

Положение и размер (атрибуты "x", "y", "w", "h"): позиция X/Y (ширина/высота) являются целыми числами на сетке 1,000,000². Эти значения единичной сетки преобразуются в значения экранной сетки во время игры в зависимости от размера и соотношения сторон экрана. Это означает, что кнопки могут выглядеть растянутыми при изменении разрешения, но позволяет обеспечить нормальный вид для разных соотношений сторон экрана.
Форма (атрибут "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": игрок авторизован в RCON (админ-панели).
- "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". Если не указано, автоматически устанавливается 1.
  - "emoticon": Открывает меню эмотиконов (не работает с биндами).
  - "spectate": Открывает меню наблюдателя (не работает с биндами).
  - "swap-action": Переключает активное действие (стрельба и хук) для прямого касания и виртуальных джойстиков.
  - "use-action": Использует активное действие в текущем направлении прицела.
  - "joystick-action": Виртуальный джойстик, который использует активное действие.
  - "joystick-aim": Виртуальный джойстик только для прицеливания без действий.
  - "joystick-fire": Виртуальный джойстик, который всегда стреляет.
  - "joystick-hook": Виртуальный джойстик, который всегда использует хук.
- Поведение бинда (атрибут "type" установлен в "bind"). Кнопки с таким поведением выполняют консольные команды как обычные горячие клавиши.
  - Атрибут "label" указывает название кнопки.
  - Атрибут "label-type" указывает тип названия кнопки:
    - "plain": Название используется как есть. Если не указано, используется автоматически.
    - "localized": Название переводится на язык игры. Работает только для стандартных кнопок, для которых есть переводы.
    - "icon": Вместо текста используется иконка. Иконки кодируются как \uXXXX, например \uf3ce для иконки телефона. Иконка должна быть доступна в наборе иконок DDNet Font Awesome Free.
  - Атрибут "command" указывает команду для выполнения при использовании кнопки, например "+fire" для кнопки стрельбы.
- Поведение переключающегося бинда (атрибут type установлен в "bind-toggle"). Кнопки с таким поведением переключаются между двумя или более командами.
  - Атрибут "commands" указывает список из двух или более команд в порядке их переключения. Каждая команда содержит атрибуты "label", "label-type" и "command", которые работают так же, как в обычных биндах. В списке должно быть минимум две команды.

Корневой объект дополнительно имеет следующие атрибуты:

"direct-touch-ingame": задаёт режим прямого сенсорного ввода во время игры. Возможные значения:
- "disabled": прямой сенсорный ввод не используется во время игры. Это означает, что необходим виртуальный джойстик.
- "action": прямой сенсорный ввод использует активное действие (см. выше).
- "aim": прямой сенсорный ввод только изменяет позицию прицеливания без использования действия. Это означает необходимость отдельных кнопок для использования действий.
- "fire": прямой сенсорный ввод всегда использует выстрел.
- "hook": прямой сенсорный ввод всегда использует крюк.
"direct-touch-spectate": задаёт режим прямого сенсорного ввода во время наблюдения. Возможные значения:
- "disabled": прямой сенсорный ввод не используется во время наблюдения. Это означает, что необходим виртуальный джойстик.
- "aim": прямой сенсорный ввод используется для наблюдения.
"background-color-inactive" (добавлено в DDNet 19.0): задаёт цвет фона неактивных сенсорных кнопок. Подробнее о формате цвета см. ниже.
"background-color-active" (добавлено в DDNet 19.0): задаёт цвет фона активных сенсорных кнопок. Подробнее о формате цвета см. ниже.

Формат цвета

Цвета задаются в виде шестнадцатеричных строк в форматах RRGGBBAA, RRGGBB, RGBA и RGB без какого-либо префикса по типу #, например "A526C440". Если значение альфа не указано, то по умолчанию выставляется полная непрозрачность.

Внутриигровые кнопки меню

В дополнение к отдельным сенсорным элементам управления на экране, при включённом cl_touch_controls на главной странице игрового меню добавляется вторая строка для менее часто используемых функций, которые иначе невозможно использовать без клавиатуры:

Кнопки для открытия локальной и удалённой консоли. Открытие локальной консоли без сенсорного управления полезно, так как там отображаются сообщения об ошибках, если конфигурация сенсорного управления не может быть загружена.
Кнопка для закрытия меню, что удобнее, чем использование виртуальной кнопки «Назад», если она не всегда отображается.
Флажок для переключения интерфейса редактора сенсорного управления (см. ниже).

Внутриигровой эдитор сенсорного управления

Пользовательский интерфейс для настройки сенсорного управления отображается на главном экране внутриигрового меню, когда он включен. На данный момент редактор сенсорных элементов управления ограничен базовыми функциями управления конфигурацией.

Сохранение конфигурации в файл touch_controls.json в каталоге конфигурации.
Отмена текущих изменений путём повторной загрузки файла touch_controls.json из каталога конфигурации.
Восстановление конфигурации по умолчанию путём повторной загрузки файла touch_controls.json из каталога данных.
Отображение информации о наличии несохранённых изменений.
Импорт и экспорт конфигурации из буфера обмена и в буфер обмена. Это единственный способ редактировать конфигурацию на новых версиях Android, так как редактирование файлов в хранилище приложений больше невозможно.

Кроме того, в этом пользовательском интерфейсе можно настроить глобальные параметры сенсорного управления:

Режимы прямого сенсорного ввода в игре и при наблюдении (см. формат конфигурации сенсорных кнопок) можно настроить с помощью выпадающих меню.

Когда редактор сенсорных элементов управления активен, все сенсорные кнопки отображаются независимо от их видимости, чтобы лучше поддерживать расположение кнопок.

Настройки элементов управления

Экспортируйте конфигурацию сенсорного управления в буфер обмена.
Сохраните содержимое буфера обмена в файл, чтобы вам было удобнее его редактировать. Также рекомендуется сделать это для создания резервной копии вашей конфигурации!
Отредактируйте конфигурацию (подробности о формате см. выше).
Скопируйте отредактированную конфигурацию обратно в буфер обмена и импортируйте её в клиент снова. Если конфигурация не загрузилась успешно, проверьте локальную консоль на наличие сообщений об ошибках, содержащих touch_controls, и исправьте конфигурацию соответственно. Используйте онлайн-инструменты для проверки и форматирования JSON.
Сохраните изменения в клиенте после завершения. Вы также можете отменить свои изменения или восстановить конфигурацию по умолчанию, если что-то пошло не так.

Планируется более удобный пользовательский интерфейс для прямого редактирования сенсорного управления в клиенте.

Примечание: вы также можете редактировать файл touch_controls.json напрямую в каталоге конфигурации вместо экспорта/импорта через буфер обмена, но это не поддерживается на Android.

Примеры

Пример общей структуры сенсорной конфигурации:

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

Пример кнопки с поведением "bind", которая выводит сообщение в чат:

{
    "x": 500000,
    "y": 500000,
    "w": 100000,
    "h": 100000,
    "shape": "rect",
    "visibilities": [
    ],
    "behavior": {
        "type": "bind",
        "label": "Example",
        "label-type": "plain",
        "command": "echo Hello world!"
    }
}

Пример кнопки с поведением "predefined" для виртуального джойстика, который использует активное действие:

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

Пример кнопки с поведением "bind-toggle", которая переключается между выводом трёх разных сообщений в чат:

{
    "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"
            }
        ]
    }
}

Возможные проблемы

Проблема на Android: Нажатие 3 и более пальцев одновременно вызывает мгновенное отпускание всех пальцев.
- Решение: Это вызвано особенностями вашего телефона, которые обрабатывают глобальные жесты с несколькими пальцами. Откройте приложение «Настройки» и отключите функции жестов, связанные с 3 и более пальцами (поиск по запросу «3 пальца»). В частности, отключите функции «Смахивание вниз тремя пальцами для скриншота», «Нажатие и удержание тремя пальцами для скриншота» и «Смахивание вверх тремя пальцами для входа в режим разделённого экрана».
Проблема на Android: Иногда касание в верхней части экрана, примерно в зоне 15%, не работает вовсе или работает очень нестабильно.
- Решение: Причина этого неясна. Проблему можно решить, перезапустив приложение. Также может помочь возврат на главный экран.

Детали осуществления

Ниже приведены детали реализации сенсорного управления для разработчиков.

Сенсорное управление в игре реализовано в отдельном клиентском компоненте CTouchControls в файлах src/game/client/components/touch_controls.cpp и src/game/client/components/touch_controls.h. По возможности бинды используются напрямую как поведение кнопок вместо использования предопределённого поведения для уменьшения сложности.

При добавлении собственного поведения кнопок в форкнутом клиенте рекомендуется добавлять префикс к именам новых форм, видимости, поведения и т.д. с названием вашего форка, например, myfork.octagon, если вы добавляете новую форму для восьмиугольных кнопок, чтобы избежать конфликтов в будущих версиях.

Чтобы добавить поддержку сенсорного управления для других игровых клиентских компонентов, таких как колесо эмоций и меню зрителя, используйте функцию CUi::UpdateTouchState, как для колеса эмоций и меню зрителя. Убедитесь, что ваш компонент обрабатывает KEY_ESCAPE для закрытия самого себя, что также соответствует кнопке «Назад» на Android. Обратите внимание, что только один компонент может использовать сенсорное состояние в каждом кадре, поэтому невозможно одновременно удерживать сенсорную кнопку в игре и использовать другой компонент, например колесо эмоций, другими пальцами. Вместо этого соответствующее предопределённое поведение сенсорной кнопки (например, CSpectateTouchButtonBehavior) активирует игровой компонент (например, меню зрителя) в своей функции OnDeactivate, но не деактивирует его снова. Активация компонента в функции OnActivate уже вызвала бы влияние пальца, который активировал кнопку, на активированный компонент.

Ссылки

Стандартная конфигурация сенсорных кнопок:

https://github.com/ddnet/ddnet/blob/69c92a79e6bab9f9390245f518c5340222c544dc/data/touch_controls.json

Запрос на добавление сенсорного управления в движок и интерфейс:

https://github.com/ddnet/ddnet/pull/8621

Запрос на добавление внутриигрового сенсорного управления:

https://github.com/ddnet/ddnet/pull/8632

Запрос на добавление сенсорных элементов для эмоций и режима зрителя:

https://github.com/ddnet/ddnet/pull/8801