Touch controls/ru: Difference between revisions
Кiлiбiк off (talk | contribs) Created page with "В дополнение к отдельным сенсорным элементам управления на экране, при включённом <code>cl_touch_controls</code> на главной странице игрового меню добавляется вторая строка для менее часто используемых функций, которые иначе невозможно использовать без клавиатуры:" |
Кiлiбiк off (talk | contribs) Created page with "*Кнопки для открытия локальной и удалённой консоли. Открытие локальной консоли без сенсорного управления полезно, так как там отображаются сообщения об ошибках, если конфигурация сенсорного управления не может быть загружена. *Кнопка для закрытия меню, что у..." |
||
Line 123: | Line 123: | ||
В дополнение к отдельным сенсорным элементам управления на экране, при включённом <code>cl_touch_controls</code> на главной странице игрового меню добавляется вторая строка для менее часто используемых функций, которые иначе невозможно использовать без клавиатуры: | В дополнение к отдельным сенсорным элементам управления на экране, при включённом <code>cl_touch_controls</code> на главной странице игрового меню добавляется вторая строка для менее часто используемых функций, которые иначе невозможно использовать без клавиатуры: | ||
*Кнопки для открытия локальной и удалённой консоли. Открытие локальной консоли без сенсорного управления полезно, так как там отображаются сообщения об ошибках, если конфигурация сенсорного управления не может быть загружена. | |||
* | *Кнопка для закрытия меню, что удобнее, чем использование виртуальной кнопки «Назад», если она не всегда отображается. | ||
* | *Флажок для переключения интерфейса редактора сенсорного управления (см. ниже). | ||
* | |||
<span id="Ingame_touch_controls_editor"></span> | <span id="Ingame_touch_controls_editor"></span> |
Revision as of 10:50, 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"
корневого объекта определяет массив объектов сенсорного управления. Каждый объект сенсорного управления имеет следующие настраиваемые свойства:
- 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"
. If no"number"
is given, it will be set to1
automatically.
- The attribute
"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. If no"label-type"
is given, it will be set to"plain"
automatically."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 unicodef3ce
. 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.
- The attribute
- 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 attribute
- Predefined behavior (attribute
Корневой объект дополнительно имеет следующие атрибуты:
"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
на главной странице игрового меню добавляется вторая строка для менее часто используемых функций, которые иначе невозможно использовать без клавиатуры:
- Кнопки для открытия локальной и удалённой консоли. Открытие локальной консоли без сенсорного управления полезно, так как там отображаются сообщения об ошибках, если конфигурация сенсорного управления не может быть загружена.
- Кнопка для закрытия меню, что удобнее, чем использование виртуальной кнопки «Назад», если она не всегда отображается.
- Флажок для переключения интерфейса редактора сенсорного управления (см. ниже).
Внутриигровой эдитор сенсорного управления

Пользовательский интерфейс для настройки сенсорного управления отображается на главном экране внутриигрового меню, когда он включен. На данный момент редактор сенсорных элементов управления ограничен базовыми функциями управления конфигурацией.
- 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.
Кроме того, в этом пользовательском интерфейсе можно настроить глобальные параметры сенсорного управления:
- Режимы прямого сенсорного ввода в игре и при наблюдении (см. формат конфигурации сенсорных кнопок) можно настроить с помощью выпадающих меню.
Когда редактор сенсорных элементов управления активен, все сенсорные кнопки отображаются независимо от их видимости, чтобы лучше поддерживать расположение кнопок.
Настройки элементов управления
- 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.
Примеры
Пример общей структуры сенсорной конфигурации:
{
"direct-touch-ingame": "action",
"direct-touch-spectate": "aim",
"background-color-inactive": "00000040",
"background-color-active": "33333340",
"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"
}
}
Пример кнопки с поведением "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%, не работает вовсе или работает очень нестабильно.
- Решение: Причина этого неясна. Проблему можно решить, перезапустив приложение. Также может помочь возврат на главный экран.
Детали осуществления
These are details about the implementation of the touch controls intended for developers.
Сенсорное управление в игре реализовано в отдельном клиентском компоненте 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/pull/8621
- Запрос на добавление внутриигрового сенсорного управления:
https://github.com/ddnet/ddnet/pull/8632
- Запрос на добавление сенсорных элементов для эмоций и режима зрителя: