478 строк · 35 КиБ
code/crates/chl-input/GAMEPAD-DESIGN.md
| 1 | # Геймпад: разведка, план и только-читающий слой (перехвата ввода пока нет) |
| 2 | |
| 3 | Это ответ на пункт 8 фазы 5 `ROADMAP.md` — «нативный слой геймпада: профиль |
| 4 | на игру, экранная клавиатура, гироскоп и тачпады через виртуальный геймпад |
| 5 | на evdev и uinput». Самый тяжёлый пункт фазы, и не только по объёму: это |
| 6 | устройство-уровневый ввод-вывод, где ошибка выглядит как залипшая клавиша, |
| 7 | неотпускаемая кнопка мыши или отобранный у компоновщика пад — то есть как |
| 8 | сломанный сеанс, а не как сообщение об ошибке. |
| 9 | |
| 10 | Поэтому проход построен так же, как CAS и обновления Wine: сначала разведка |
| 11 | на живой машине, потом дизайн, и реализовано только то, в чём появилась |
| 12 | настоящая уверенность. Реализована **нижняя, только читающая половина** — |
| 13 | крейт `chl-input` и команда `chl gamepad`: перечисление устройств, |
| 14 | классификация, обнаружение горячего подключения, диагностика прав. Верхняя, |
| 15 | рискованная половина — синтез событий через `/dev/uinput` — здесь описана, |
| 16 | но не написана. |
| 17 | |
| 18 | Ссылки на исходник StartWine ниже — на |
| 19 | `~/Games/StartWine/data/scripts/sw_input.py` (1463 строки), референс только |
| 20 | на чтение. |
| 21 | |
| 22 | ## Что именно делает StartWine, разобрано по строкам |
| 23 | |
| 24 | Важно понимать: поддержка геймпада в StartWine **не проброс, а активное |
| 25 | переназначение**. Она не помогает игре увидеть пад — она превращает пад в |
| 26 | клавиатуру и мышь. |
| 27 | |
| 28 | | Что | Где | Механизм | |
| 29 | |---|---|---| |
| 30 | | Доступ к устройствам | `sw_input.py:87-88` | `python-evdev` — тонкая обёртка над ioctl-ами evdev/uinput | |
| 31 | | Горячее подключение | `sw_input.py:1293-1307` | опрос `evdev.list_devices()` раз в 0.5 с, сопоставление **по названию устройства** | |
| 32 | | Переподключение | там же | на `OSError` цикл просто продолжает опрос по имени, пока пад не появится снова, и открывает новый дескриптор | |
| 33 | | Синтез | `sw_input.py:295` | **одно** виртуальное устройство `UInput.from_device(*mouse, *keyboard, name='SwKeyPad')` — способности клавиатуры и мыши слиты в одном узле | |
| 34 | | Перевод событий | `sw_input.py:414-560` | кнопка → `KEY_*`/`BTN_*`, ось → `REL_*` с разгоном и удержанием на упоре | |
| 35 | | Отбор геймпадов | `sw_input.py:107-149`, `1317` | чёрный список подстрок в названии плюс «умеет ли `EV_FF`» | |
| 36 | | Профили | `sw_data.py` | **один глобальный** профиль, плюс отдельный для навигации по интерфейсу; на игру — только выключатель `SW_USE_CONTROLLER` | |
| 37 | | Экранная клавиатура | `sw_input.py:643-806` | обычный GTK-виджет; геймпадом она управляется **как побочный эффект** — крестовина переназначена на стрелки, а стрелки GTK и так понимает | |
| 38 | | Аккорды | `sw_input.py:564-641` | класс `SwKeyController`, только чтение, к переназначению отношения не имеет | |
| 39 | |
| 40 | Два вывода, которые определяют весь дизайн ниже. |
| 41 | |
| 42 | **Первый: реальное устройство никогда не захватывается.** `EVIOCGRAB` в |
| 43 | `sw_input.py` не вызывается ни разу. Значит игра с честной поддержкой |
| 44 | джойстика продолжает видеть пад сама, независимо от переназначения. Это |
| 45 | свойство надо сохранить: захват удобнее (не будет двойных нажатий), но он |
| 46 | отбирает устройство у всех остальных, включая компоновщик и Steam. |
| 47 | |
| 48 | **Второй: `SW_USE_CONTROLLER` не делает ничего.** Настройка не встречается в |
| 49 | `sw_runlib` ни разу — только в коде интерфейса. У нас она перенесена как |
| 50 | мёртвая (`chl-core/src/settings.rs`, список `NO_EFFECT`), и именно эта |
| 51 | работа делает её живой. |
| 52 | |
| 53 | ## Выбор крейта: `evdev`, а не `evdev-rs`, `input-linux` или `gilrs` |
| 54 | |
| 55 | Проверено `cargo info` и `cargo search`, 2026-09-03: |
| 56 | |
| 57 | | Крейт | Версия и дата | Что не так | |
| 58 | |---|---|---| |
| 59 | | **`evdev` 0.13.2** | 15.09.2025, 1.6 млн загрузок | **выбран** | |
| 60 | | `evdev-rs` 0.6.3 | 14.09.2025, 415 тыс. | биндинг к `libevdev` — системная библиотека на C, которую надо искать при сборке | |
| 61 | | `input-linux` 0.7.1 | 19.08.2024, 146 тыс. | сырые обёртки ioctl, эргономики почти нет, свежих релизов больше года | |
| 62 | | `gilrs` 0.11.2 | 30.05.2026, 8.2 млн | **только чтение**: uinput не умеет вовсе, а нам нужен синтез. Плюс `libudev-sys` — снова C | |
| 63 | |
| 64 | `evdev` 0.13.2 — чистый Rust, зависимости `bitvec`, `cfg-if`, `libc`, `nix`, |
| 65 | ни одной системной библиотеки. Даёт ровно то же, что `python-evdev`: |
| 66 | перечисление, чтение способностей, `grab`/`ungrab`, `EVIOCGUNIQ`/`EVIOCGPHYS`, |
| 67 | виброотдачу, и `uinput::VirtualDeviceBuilder` с `enumerate_dev_nodes_blocking()` |
| 68 | — последнее позволяет узнать, каким `/dev/input/eventN` оказалось только что |
| 69 | созданное виртуальное устройство, и потому делает round-trip проверяемым. |
| 70 | |
| 71 | ## Разведка на живой машине: пять фактов, добытых опытом |
| 72 | |
| 73 | Всё ниже — не рассуждения, а результат прогона на этой машине (CachyOS, |
| 74 | 2026-09-03). Прототип лежал в scratchpad и в репозиторий не попал; всё, что |
| 75 | он показал, воспроизводится командой `chl gamepad`. |
| 76 | |
| 77 | ### 1. Пад в доме есть, но прямо сейчас он выключен |
| 78 | |
| 79 | ``` |
| 80 | /dev/input/by-id/usb-8BitDo_Ultimate_2_58EB9DA57B-hidraw -> ../../hidraw7 |
| 81 | ``` |
| 82 | |
| 83 | Приёмник 8BitDo Ultimate 2 воткнут, серийный номер `58EB9DA57B` виден, а вот |
| 84 | узла `event*` у него нет ни одного, и в `/proc/bus/input/devices` его тоже |
| 85 | нет. То есть донгл перечислен, а сам пад не включён. Для проверки |
| 86 | переподключения это удача, а не помеха: сценарий «включил кнопкой посреди |
| 87 | игры» проверяется ровно этим падом, живьём, без разборки. |
| 88 | |
| 89 | ### 2. `/dev/uinput` открывается — но доступ пришёл от чужих пакетов |
| 90 | |
| 91 | ``` |
| 92 | $ chl gamepad access |
| 93 | ок /dev/uinput: открывается на запись |
| 94 | ! Откуда доступ: от чужих пакетов: |
| 95 | /usr/lib/udev/rules.d/40-kdeconnect-uinput.rules |
| 96 | /usr/lib/udev/rules.d/60-steam-input.rules (пакет steam-devices) |
| 97 | /usr/lib/udev/rules.d/71-uinput-dev-early-creation.rules (пакет game-devices-udev) |
| 98 | ``` |
| 99 | |
| 100 | Все три содержат одну и ту же строку |
| 101 | `KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess"`. **StartWine не ставит |
| 102 | ни одного своего udev-правила** — его геймпадная поддержка годами держится |
| 103 | на том, что у пользователя установлен Steam, и нигде об этом не сказано. |
| 104 | Снести `steam-devices` и `game-devices-udev` — и `/dev/uinput` вернётся к |
| 105 | `root:root 0600`, а переназначение молча перестанет работать. |
| 106 | |
| 107 | Отсюда решение: **лаунчер предлагает своё правило** (`chl gamepad rule`, |
| 108 | текст в `access::RULE_TEXT`), но не ставит его сам — файл в |
| 109 | `/etc/udev/rules.d` кладётся через sudo, и делать это за спиной у человека |
| 110 | лаунчер не будет. |
| 111 | |
| 112 | ### 3. Синтетическому устройству нужен полный набор способностей, иначе оно недоступно даже своему создателю |
| 113 | |
| 114 | Самая неочевидная находка прохода. Виртуальное устройство было создано |
| 115 | дважды, с разным набором способностей: |
| 116 | |
| 117 | | Что объявили | Что получилось | |
| 118 | |---|---| |
| 119 | | `BTN_SOUTH` + одна ось `ABS_X` | `root:input 0660`, **ACL нет**, `open()` даёт `EACCES` даже создателю; ждали 5 секунд — не появился | |
| 120 | | 11 кнопок + `ABS_X/Y`, `ABS_RX/RY`, `ABS_HAT0X/Y` | `ID_INPUT_JOYSTICK=1`, `TAGS=:seat:uaccess:`, ACL `user:fanchji:rw-` через **~50 мс**, открывается | |
| 121 | |
| 122 | Причина: `/usr/lib/udev/rules.d/70-uaccess.rules:61` выдаёт `uaccess` по |
| 123 | условию `SUBSYSTEM=="input", ENV{ID_INPUT_JOYSTICK}=="?*"`, а этот признак |
| 124 | ставит udev-встройка `input_id`, и ей нужна **пара** координатных осей, а не |
| 125 | одна. Неполный набор способностей — и устройство остаётся недоступным |
| 126 | обычному процессу. |
| 127 | |
| 128 | Следствий два, и оба важны для будущего синтеза: |
| 129 | |
| 130 | - **Синтетический пад надо объявлять целиком**, даже если игра пользуется |
| 131 | тремя кнопками. Иначе игра, читающая `/dev/input/event*` от имени |
| 132 | пользователя (а SDL делает именно так), нашего пада просто не увидит. |
| 133 | - **Между созданием узла и правом его открыть проходит время** — здесь |
| 134 | ~50 мс. Открывать надо с повтором, а не один раз. |
| 135 | |
| 136 | Для устройства, синтезирующего клавиатуру и мышь (то, что делает StartWine), |
| 137 | эта проблема не встаёт: такие события читает компоновщик, а у него доступ |
| 138 | привилегированный. Но для «виртуального геймпада» из формулировки ROADMAP — |
| 139 | встаёт в полный рост, и это надо знать до того, как писать код. |
| 140 | |
| 141 | ### 4. Round-trip работает, и уборка бесплатна |
| 142 | |
| 143 | Событие, записанное в `/dev/uinput`, прочиталось из своего же узла без |
| 144 | искажений: |
| 145 | |
| 146 | ``` |
| 147 | прочитано: ["KEY/304=1", "SYNCHRONIZATION/0=0", "KEY/304=0", "SYNCHRONIZATION/0=0"] |
| 148 | ``` |
| 149 | |
| 150 | `304` — это `BTN_SOUTH`. После `drop` дескриптора узел исчезает сам: |
| 151 | `/dev/input/event25 существует после drop: false`. Отдельного `UI_DEV_DESTROY` |
| 152 | и отдельной уборки в тестах не нужно — гарантия даётся ядром при закрытии |
| 153 | дескриптора, значит она работает и при панике, и при раннем возврате. |
| 154 | |
| 155 | ### 5. Сопоставление по одному названию ломается — поймано на живом железе |
| 156 | |
| 157 | Первая версия сравнения снимков повторяла StartWine буквально: ключ |
| 158 | устройства — его название. Запуск `chl gamepad watch --all` на этой машине |
| 159 | выдал бесконечный поток фантомных переездов: |
| 160 | |
| 161 | ``` |
| 162 | ~ переехал Razer Razer Basilisk V3 Pro — /dev/input/event20 → /dev/input/event3 |
| 163 | ~ переехал Razer Razer Basilisk V3 Pro — /dev/input/event24 → /dev/input/event3 |
| 164 | ~ переехал Razer Razer Ornata V2 — /dev/input/event11 → /dev/input/event2 |
| 165 | ... и так каждые 300 мс, вечно |
| 166 | ``` |
| 167 | |
| 168 | Причина: одно USB-устройство даёт несколько узлов `eventN`. У мыши Basilisk |
| 169 | их три (мышь, клавиатурный интерфейс, макро-интерфейс), и у всех трёх |
| 170 | одинаковое название, одинаковые `vid:pid` **и одинаковый серийный номер** — |
| 171 | `000000000000`, заглушка вместо настоящего. Ключ из названия склеивает три |
| 172 | узла в одно устройство, и сравнение снимков честно сообщает, что оно |
| 173 | мечется между ними. |
| 174 | |
| 175 | В StartWine этот дефект тоже есть — он просто не всплывает, потому что там |
| 176 | отслеживается ровно один выбранный пад, а не весь список. Портировать его |
| 177 | вместе с механизмом было бы легко и незаметно. |
| 178 | |
| 179 | Исправление — двухуровневая идентичность (`device::Identity`): |
| 180 | |
| 181 | - **`key()`** — строгий ключ узла: серийный номер (если он настоящий, а не |
| 182 | заглушка) или `vid:pid` с названием, **плюс физический путь** |
| 183 | `EVIOCGPHYS` вида `usb-0000:0f:00.0-1/input0`. У разных интерфейсов одного |
| 184 | устройства он разный, у выключенного и включённого обратно пада — тот же. |
| 185 | По нему сравниваются снимки. |
| 186 | - **`family()`** — то же без физического пути. Отвечает на вопрос «это тот |
| 187 | пад, с которым я работал?», а не «это тот же узел». Нужен, когда пад |
| 188 | переткнули в другой USB-порт. |
| 189 | |
| 190 | Плюс `real_uniq()` отбрасывает серийные-заглушки (`000000000000`, |
| 191 | `00:00:00:00:00:00`, пустая строка). |
| 192 | |
| 193 | ## Что реализовано в этом проходе |
| 194 | |
| 195 | Крейт `chl-input`, три модуля, **ни одного вызова, изменяющего состояние |
| 196 | системы**: `/dev/uinput` открывается только в диагностике прав и сразу |
| 197 | закрывается, `ioctl(UI_DEV_CREATE)` не вызывается ни разу, `EVIOCGRAB` не |
| 198 | вызывается ни разу. |
| 199 | |
| 200 | ### `device` — перечисление и классификация |
| 201 | |
| 202 | Классификация идёт **по способностям устройства, а не по названию**. Это |
| 203 | прямое расхождение со StartWine, и намеренное: его чёрный список подстрок |
| 204 | (`'POWERBUTTON', 'SPEAKER', 'HDA', …`) английский, и устройство с русским |
| 205 | или китайским названием проходит мимо него целиком, а признак «умеет |
| 206 | `EV_FF`» отсеивает любой пад без вибромотора и, наоборот, зачисляет в |
| 207 | геймпады руль или тактильную мышь. |
| 208 | |
| 209 | Вместо этого повторено правило udev-встройки `input_id` — той самой, что |
| 210 | ставит `ID_INPUT_JOYSTICK`: **пара осей `ABS_X`/`ABS_Y` плюс хоть одна |
| 211 | игровая кнопка** (`BTN_TRIGGER…BTN_DEAD`, `BTN_SOUTH…BTN_THUMBR`, |
| 212 | `BTN_DPAD_*`) **или дополнительная ось** (`ABS_RX…ABS_HAT3Y`). Совпадать с |
| 213 | udev здесь обязательно, а не желательно: именно `ID_INPUT_JOYSTICK` решает, |
| 214 | дадут ли нам ACL на устройство. Разойдись мы с udev — и в списке будут |
| 215 | устройства, которые физически не открыть. |
| 216 | |
| 217 | Повторено, а не взято готовым, чтобы не тянуть `libudev` ради трёх битов, |
| 218 | которые и так лежат в способностях устройства. |
| 219 | |
| 220 | Порядок проверок — геймпад, клавиатура, мышь, прочее — тоже не случаен: пады |
| 221 | часто объявляют себя заодно клавиатурой (кнопка «домой» шлёт |
| 222 | `KEY_HOMEPAGE`), и проверка на клавиатуру, стоящая первой, забрала бы их |
| 223 | себе. |
| 224 | |
| 225 | Ошибки открытия не глотаются, а возвращаются отдельным списком |
| 226 | (`Skipped::Denied` / `Skipped::Failed`): «геймпада нет» и «геймпад есть, но |
| 227 | нам не дали его открыть» — разные беды с разными решениями. |
| 228 | |
| 229 | ### `hotplug` — сравнение снимков и опрос |
| 230 | |
| 231 | Механизм намеренно повторяет StartWine: опрос `/dev/input` раз в 500 мс, |
| 232 | сопоставление по устойчивому имени. Выглядит примитивно рядом с подпиской на |
| 233 | события udev через netlink, и всё же выбран опрос: |
| 234 | |
| 235 | 1. **Он проверен на том самом сценарии, ради которого всё делается.** Цикл |
| 236 | «попробовать открыть, поймать ошибку, вернуться к опросу» переживает любую |
| 237 | ошибку, потому что состояния между итерациями у него нет вовсе. |
| 238 | 2. **Подписка тянет `libudev`** — снова системная библиотека на C. |
| 239 | Полсотни `readdir` раз в полсекунды стоят меньше. |
| 240 | 3. **Netlink всё равно не отменяет повторного открытия с ожиданием.** Между |
| 241 | появлением узла и правом его открыть проходит ~50 мс (см. находку 3), |
| 242 | значит повтор нужен в любом случае. |
| 243 | |
| 244 | Само сравнение — чистая функция `diff(prev, next) -> Vec<Change>` с тремя |
| 245 | исходами: `Connected`, `Disconnected`, `Moved`. Порядок результата |
| 246 | детерминирован (сначала отключения, потом переезды, потом подключения, |
| 247 | внутри группы — по ключу), иначе один и тот же набор изменений печатался бы |
| 248 | каждый раз по-новому. |
| 249 | |
| 250 | Чистота здесь сделана ради тестов: все 10 тестов `hotplug` работают на |
| 251 | выдуманных списках устройств, без железа и без `/dev`. Включать пад, чтобы |
| 252 | проверить логику переподключения, не нужно. |
| 253 | |
| 254 | ### `access` — права и udev-правило |
| 255 | |
| 256 | `chl gamepad access` отвечает на три вопроса: открывается ли `/dev/uinput`, |
| 257 | **от какого чужого пакета** этот доступ зависит, и сколько узлов |
| 258 | `/dev/input/event*` закрыто. `chl gamepad rule` печатает текст правила, |
| 259 | снимающего зависимость от Steam: |
| 260 | |
| 261 | ``` |
| 262 | KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess", OPTIONS+="static_node=uinput" |
| 263 | SUBSYSTEM=="input", ATTRS{name}=="Chimera *", TAG+="uaccess" |
| 264 | ``` |
| 265 | |
| 266 | Первая строка — то же, что делают `steam-devices` и `game-devices-udev`. |
| 267 | Второй строки в чужих правилах нет: она страхует от находки 3 — если наше |
| 268 | синтетическое устройство почему-то не будет признано джойстиком, ACL ему |
| 269 | всё равно достанется, по названию, которое мы задаём сами. |
| 270 | |
| 271 | Проверка «открывается ли `/dev/uinput`» сделана настоящим `open()` на |
| 272 | запись, а не `access(2)`: ACL, LSM и пространства имён дают разные ответы, и |
| 273 | верить можно только тому же вызову, который сделает рабочий код. Устройство |
| 274 | при этом не создаётся — его создаёт `ioctl(UI_DEV_CREATE)`, а он не |
| 275 | вызывается. |
| 276 | |
| 277 | ### Команда |
| 278 | |
| 279 | ``` |
| 280 | chl gamepad list [--all] что подключено сейчас |
| 281 | chl gamepad watch [--all] следить за подключением, Ctrl-C чтобы выйти |
| 282 | chl gamepad access права: есть ли доступ и от чего он зависит |
| 283 | chl gamepad rule текст udev-правила (только печатает) |
| 284 | ``` |
| 285 | |
| 286 | ## Что осталось дизайном: синтез событий |
| 287 | |
| 288 | Ниже — план, который стоит сверить с владельцем перед тем, как писать код. |
| 289 | |
| 290 | ### Профили привязок: TOML, и на игру, а не один на всех |
| 291 | |
| 292 | StartWine держит **один глобальный** профиль привязок плюс отдельный для |
| 293 | навигации по интерфейсу; на игру приходится только выключатель. Это его |
| 294 | главное функциональное ограничение: раскладка, удобная в стратегии, в |
| 295 | шутере не годится, и переключать её приходится вручную перед запуском. |
| 296 | |
| 297 | Предлагается формат в духе `GameConfig`: секция в конфиге игры, значения |
| 298 | проверяются при чтении, неизвестный ключ — ошибка, а не молчаливое |
| 299 | игнорирование. |
| 300 | |
| 301 | ```toml |
| 302 | [gamepad] |
| 303 | profile = "shooter" # имя профиля из ~/.config/chimera-launcher/gamepad/ |
| 304 | [gamepad.buttons] |
| 305 | BTN_SOUTH = "KEY_SPACE" |
| 306 | BTN_EAST = "BTN_RIGHT" |
| 307 | BTN_START = "KEY_ESC" |
| 308 | [gamepad.axes] |
| 309 | ABS_X = { to = "REL_X", speed = 12.0, deadzone = 3000 } |
| 310 | ABS_Y = { to = "REL_Y", speed = 12.0, deadzone = 3000 } |
| 311 | ABS_HAT0X = { negative = "KEY_LEFT", positive = "KEY_RIGHT" } |
| 312 | ``` |
| 313 | |
| 314 | Имена кодов — настоящие имена ядра (`KEY_SPACE`, `BTN_RIGHT`), а не свои |
| 315 | выдуманные: они уже канонические, документированы в `linux/input-event-codes.h`, |
| 316 | и `evdev` умеет разбирать их в обе стороны. Свой словарь стал бы вторым |
| 317 | источником правды, который однажды разойдётся с ядром. |
| 318 | |
| 319 | Профили лежат отдельными файлами и переиспользуются между играми: в конфиге |
| 320 | игры — только имя профиля, чтобы правка раскладки не требовала обходить |
| 321 | двадцать конфигов. |
| 322 | |
| 323 | ### Настройки реестра, которые для этого нужны |
| 324 | |
| 325 | Существующая мёртвая настройка становится живой, плюс две новые. Правило |
| 326 | проекта — у `Spec` нет `Default`, поэтому `doc` и `impact` пропустить нельзя: |
| 327 | |
| 328 | ```rust |
| 329 | Spec { |
| 330 | legacy_key: "SW_USE_CONTROLLER", |
| 331 | key: "controller", |
| 332 | title: "Геймпад как клавиатура и мышь", |
| 333 | kind: Kind::Flag, |
| 334 | tier: Tier::Simple, |
| 335 | default: "0", |
| 336 | doc: "Переводит нажатия геймпада в нажатия клавиш и движения мыши.", |
| 337 | impact: "Включать для игр, которые геймпада не видят вовсе. Игра при \ |
| 338 | этом продолжает видеть и сам пад — устройство не отбирается, \ |
| 339 | так что игра с честной поддержкой джойстика может получить \ |
| 340 | двойное управление; для неё настройку лучше выключить.", |
| 341 | } |
| 342 | Spec { |
| 343 | legacy_key: "", // своя, в StartWine аналога нет |
| 344 | key: "gamepad_profile", |
| 345 | title: "Раскладка геймпада", |
| 346 | kind: Kind::Text, // имя файла профиля |
| 347 | tier: Tier::Advanced, |
| 348 | default: "default", |
| 349 | doc: "Какая раскладка кнопок и осей применяется к этой игре.", |
| 350 | impact: "Меняй, когда раскладка по умолчанию не подходит жанру: в \ |
| 351 | стратегии удобны стрелки, в шутере — мышь на правом стике. \ |
| 352 | Пустое значение или отсутствующий файл — раскладка default.", |
| 353 | } |
| 354 | Spec { |
| 355 | legacy_key: "", |
| 356 | key: "gamepad_device", |
| 357 | title: "Какой геймпад использовать", |
| 358 | kind: Kind::Text, // Identity::family(), пусто — первый найденный |
| 359 | tier: Tier::Expert, |
| 360 | default: "", |
| 361 | doc: "Привязка к конкретному паду, когда их подключено несколько.", |
| 362 | impact: "Нужно только если падов больше одного и лаунчер выбирает не \ |
| 363 | тот. Значение берётся из `chl gamepad list`. Пустое — первый \ |
| 364 | найденный, и это правильно почти всегда.", |
| 365 | } |
| 366 | ``` |
| 367 | |
| 368 | `controller` при этом убирается из `NO_EFFECT` в `chl-core/src/settings.rs` |
| 369 | и из `GUI_ONLY` в `chl-runtime/src/env.rs` — но **только вместе с рабочим |
| 370 | синтезом**, не раньше. Пока переназначения нет, честнее оставить настройку |
| 371 | явно мёртвой, чем показать рабочий переключатель, за которым ничего нет: |
| 372 | ровно от этого проект и уходит. |
| 373 | |
| 374 | Отдельно: настройка `controller` сейчас лежит в разделе «Античиты» |
| 375 | (`SECTIONS`), и это неверно — к античитам она отношения не имеет. При |
| 376 | оживлении её надо перенести в свой раздел «Геймпад». |
| 377 | |
| 378 | ### Устройство синтеза |
| 379 | |
| 380 | - **Одно виртуальное устройство или два.** StartWine делает одно, слитое |
| 381 | (`name='SwKeyPad'`). Соблазн разделить на «виртуальную клавиатуру» и |
| 382 | «виртуальную мышь» есть — так чище, и libinput получит корректно |
| 383 | классифицированные устройства вместо химеры. Но два устройства — это два |
| 384 | дескриптора, две уборки и два места, где может залипнуть кнопка. |
| 385 | Рекомендация: **начать с одного слитого**, как в StartWine, и разделять |
| 386 | только если libinput или компоновщик начнут вести себя странно. |
| 387 | - **Название** — с префиксом `Chimera ` (`Chimera Virtual Pad`), чтобы |
| 388 | udev-правило из `access::RULE_TEXT` его находило, и чтобы устройство было |
| 389 | узнаваемо в чужих логах. |
| 390 | - **Реальный пад не захватывается.** `EVIOCGRAB` не вызывать — сохраняем |
| 391 | свойство StartWine (см. первый вывод выше). |
| 392 | - **Уборка гарантирована закрытием дескриптора** (проверено, находка 4). |
| 393 | Отдельного обработчика паники не нужно; нужно лишь не терять владение |
| 394 | `VirtualDevice` в глобальной переменной, которая переживёт панику. |
| 395 | - **Залипание — главный риск.** При завершении работы, при потере пада и при |
| 396 | любой ошибке надо отправить «отпущено» для всех кодов, которые сейчас |
| 397 | нажаты. Значит синтезатор обязан вести список нажатого, а не быть |
| 398 | функцией без состояния. Это первое, что надо покрыть тестами. |
| 399 | |
| 400 | ### Как это тестировать без железа |
| 401 | |
| 402 | Проверено, что подход работает (находка 4): создаём виртуальный **геймпад** |
| 403 | — только `BTN_*` и `ABS_*`, никаких клавиатурных и мышиных способностей, |
| 404 | поэтому сломать сеанс ему нечем, — находим его узел через |
| 405 | `enumerate_dev_nodes_blocking()`, читаем свои же события обратно. Так |
| 406 | проверяется и синтез, и обнаружение подключения. Сквозной прогон уже сделан |
| 407 | руками: |
| 408 | |
| 409 | ``` |
| 410 | $ ./hold 3 & # синтетический пад на 3 секунды |
| 411 | $ chl gamepad watch --interval 300 |
| 412 | + появился Chimera Test Pad (1234:5678) — /dev/input/event25 |
| 413 | - пропал Chimera Test Pad (1234:5678) |
| 414 | ``` |
| 415 | |
| 416 | Такие тесты **нельзя включать в обычный `cargo test`**: они требуют |
| 417 | `/dev/uinput`, которого нет ни в контейнере сборки, ни на машине без |
| 418 | udev-правил. Место им — за `#[ignore]` или за отдельным флагом, с честным |
| 419 | сообщением, почему тест пропущен. |
| 420 | |
| 421 | Всё, что можно проверить без устройств, проверяется без них: классификация — |
| 422 | чистая функция от набора способностей, сравнение снимков — чистая функция от |
| 423 | двух списков. Из 34 тестов крейта железа не требует ни один. |
| 424 | |
| 425 | ## Порядок работ на следующий проход |
| 426 | |
| 427 | По возрастанию риска, каждый пункт самостоятелен: |
| 428 | |
| 429 | 1. **Разбор и запись профилей привязок** (`chl-input::profile`). Чистые |
| 430 | данные, ничего не трогает, тестируется целиком. Плюс `chl gamepad profile |
| 431 | show/validate`. Сюда же — разбор имён `KEY_*`/`BTN_*`/`ABS_*` в коды и |
| 432 | обратно. |
| 433 | 2. **Синтезатор с учётом нажатого** (`chl-input::synth`), но **пока без |
| 434 | подключения к реальному паду**: на входе — уже переведённые события, на |
| 435 | выходе — запись в uinput. Тесты round-trip за `#[ignore]`. Здесь же — |
| 436 | гарантия «всё отпущено при закрытии». |
| 437 | 3. **Соединение чтения и записи** — то самое переназначение. Только после |
| 438 | того, как 1 и 2 проверены живьём и владелец подтвердил формат профиля. |
| 439 | 4. **Оживление настроек** `controller` / `gamepad_profile` / |
| 440 | `gamepad_device`, перенос `controller` из раздела «Античиты» в свой. |
| 441 | 5. **Экранная клавиатура и навигация по интерфейсу** — это уже GUI, и оно |
| 442 | бесплатно следует из пункта 3 ровно так же, как в StartWine: крестовина |
| 443 | переназначена на стрелки, GTK их и так понимает. |
| 444 | |
| 445 | Гироскоп и тачпады из формулировки ROADMAP сознательно оставлены на потом: |
| 446 | это отдельная механика (виртуальный **пад**, а не клавиатура), и она упирается |
| 447 | в находку 3 — полный набор способностей и ожидание ACL, — тогда как |
| 448 | переназначение в клавиатуру и мышь в неё не упирается вовсе. |
| 449 | |
| 450 | ## Как перепроверить |
| 451 | |
| 452 | ```bash |
| 453 | # что подключено и как классифицировано |
| 454 | chl gamepad list --all |
| 455 | |
| 456 | # права и от какого чужого пакета они зависят |
| 457 | chl gamepad access |
| 458 | |
| 459 | # правило, снимающее зависимость от Steam (только печатает) |
| 460 | chl gamepad rule |
| 461 | |
| 462 | # обнаружение подключения: выключить пад кнопкой и включить обратно |
| 463 | chl gamepad watch |
| 464 | |
| 465 | # откуда взялась находка 2 — не выдумана |
| 466 | grep -rn 'uinput.*uaccess' /usr/lib/udev/rules.d/ |
| 467 | pacman -Qo /usr/lib/udev/rules.d/60-steam-input.rules |
| 468 | |
| 469 | # откуда взялась находка 3 — условие выдачи ACL джойстикам |
| 470 | sed -n '61p' /usr/lib/udev/rules.d/70-uaccess.rules |
| 471 | |
| 472 | # StartWine не ставит своих правил — ни одного файла .rules (только чтение) |
| 473 | find ~/Games/StartWine -name '*.rules' |
| 474 | |
| 475 | # тесты крейта — ни один не требует железа |
| 476 | cargo test -p chl-input |
| 477 | ``` |
| 478 |