Ввод: клавиатура

Главный клавиатурный вызов движка — ebiten.IsKeyPressed(key), где key — константа типа ebiten.Key: KeyA, KeyW, KeySpace, KeyLeft, KeyEscape и десятки других, по списку на каждую физическую клавишу. Функция возвращает bool — «зажата ли эта клавиши прямо сейчас» — и её принято вызывать каждый тик внутри Update: состояние меняется, а опрос читает свежее значение бесплатно. Это модель опроса, и она неожиданно удобна именно в играх: логика и так выполняется 60 раз в секунду, значит чтение ввода в том же месте исключает целый класс ошибок рассинхрона между событиями и состоянием мира.

Важная деталь, которую документация подчёркивает отдельно: ebiten.Key описывает физическую клавишу американской раскладки. Константа KeyQ — это клавиша, на которой Q стоит на QWERTY, а на клавиатуре Дворака — апостроф. Для игры это подарок: игрок с русской раскладкой жмёт ту же физическую кнопку, что и американец, и WASD работает одинаково без единой проверки раскладки. Символы с учётом раскладки — отдельная история, к ней вернёмся ниже. Пока запомните правило урока: движение читается в Update, один опрос за тик, и никогда — в Draw, частота которого зависит от монитора.

IsKeyPressed отвечает на вопрос «зажата ли клавиша», но у ввода есть второй вопрос — «нажата ли она только сейчас, в этом тике». Для него в пакете github.com/hajimehoshi/ebiten/v2/inpututil живут inpututil.IsKeyJustPressed и симметричная IsKeyJustReleased: первая истинна ровно в одном тике — том, где клавиша перешла из состояния «отпущена» в «нажата», — вторая зеркально отмечает отпускание. Разница не академическая: прыжок, выстрел, пауза и подтверждение в меню — дискретные действия, им нужен один импульс на нажатие, а бег и движение — непрерывные состояния, им нужно держаться, пока палец на клавише. IsKeyJustReleased достраивает пару: она истинна в тике отпускания, и на ней строятся действия с накоплением — натяжение лука держится на IsKeyPressed, а выстрел случается в тик, когда игрок отпустил KeySpace, и сила заряда к этому моменту уже посчитана KeyPressDuration в тиках. Смешение этих примитивов — источник самых шумных багов первых игр.

Документация inpututil добавляет два строгих правила. Первое: функции пакета обязаны вызываться в Update, не в Draw — причина в том, что Update может выполниться несколько раз за кадр, а кадр может выйти вообще без Update, и собранные там события размажутся или потеряются. Второе: IsKeyJustPressed всегда возвращает false для сборных констант вроде KeyShift и KeyControl, под которыми прячутся две физические клавиши — для них берите конкретные KeyShiftLeft или KeyShiftRight. Тем же пакетом удобно пользоваться списком: inpututil.AppendPressedKeys дописывает в переданный срез все зажатые клавиши разом — официальный пример клавиатуры движка именно так их и собирает, сортирует и печатает.

Для интерфейса нужно уметь называть клавиши словами, и здесь работает ebiten.KeyName(key): она возвращает имя клавиши в текущей раскладке игрока — KeyQ на QWERTY-клавиатуре даст «q», а на AZERTY даст «a», потому что физическое место одно, а буквы на них разные. Функция документирована для десктопов и браузера и возвращает пустую строку в трёх случаях: у клавиши нет физического имени, платформа не поддерживает имена или игровой цикл ещё не стартовал. Подсказка «нажмите E, чтобы подобрать» — её законное место, и хорошая привычка — выводить KeyName, а не зашивать букву в строку: на AZERTY подсказка сама станет честной.

Печатный ввод — имя героя, чат, чит-коды — это другая функция: ebiten.AppendInputChars дописывает в переданный срез рун те символы, которые игрок напечатал за тик, с учётом раскладки, регистра и модификаторов. Документация делит обязанности жёстко: AppendInputChars — локализованные символы, Key — физические клавиши, а Control и прочие модификаторы обрабатываются через IsKeyPressed. Из этой пары собирается любой текстовый режим: руны из AppendInputChars складываются в строку, Escape через IsKeyJustPressed её закрывает, Enter подтверждает. Отдельно приятная мелочь для мобильных сборок: клавиатура на Android и iOS требует фокусируемого вида приложения — документация оговаривает это прямо, и лучше знать об этом до релиза, а не после жалобы игрока.

Зачем поддерживать обе схемы сразу? Потому что они живут у разных игроков в разных руках: стрелки — правая рука на отдельном блоке, WASD — левая рука возле мыши, и эти два стиля сосуществуют в одной игре десятилетиями. Физическая модель ebiten.Key делает поддержку бесплатной: KeyA — это позиция клавиши, а не буква, поэтому русская, французская или немецкая раскладка не ломают ни одну из схем — раскладка влияет на символы, а не на клавиши. readDirection из этого урока уже читает оба слоя через ИЛИ, и единственное, что стоит вынести из этого кода дальше, — сами клавиши можно сделать данными, а не частью кода: карта «клавиша — направление» в поле структуры превращает поддержку третьей схемы управления в пару строк конфигурации, а биндинги «на горячую» — в загрузку из файла.

Второй сценарий двух слоёв — меню и игра. В интерфейсе перемещение по пунктам удобнее стрелками и подтверждается Enter, в бою работает WASD и Space; оба опрашиваются из одного Update параллельно, а экран решает, какой ввод сейчас главный. Когда пунктов меню станет много и появится история экранов, этот разбор продолжится в уроке про сцены и конечный автомат, а сейчас важно другое: опрос клавиатуры дёшев, читайте все нужные схемы каждый тик и не экономьте на вызовах — их стоимость нулевая рядом с любым DrawImage.

Три честных ограничения, о которых стоит знать заранее. Первое — мобильные платформы: физической клавиатуры у телефона нет, IsKeyPressed осмыслен только при подключённой или аппаратной клавиатуре, а пальцем по стеклу игрок будет делать то же самое через тач — это целиком тема седьмого урока, и общий каркас Update от этого не изменится. Второе — тестирование: readDirection вызывает движок напрямую, и юнит-тест её не «нажмёт»; поэтому чистую часть — сбор вектора из четырёх флагов и нормализацию — выносите в функцию без движка, а тонкий слой опроса держите в одну строку вызова, как в коде этого урока. Третье — дисциплина места: ввод опрашивается в Update и складывается в поля структуры, Draw эти поля только читает; как только ввод начинает читаться в отрисовке, скорость игры начинает зависеть от монитора — та же болезнь, что и с движением в Draw из пятого урока. Отдельно у пакета есть списочные варианты AppendJustPressedKeys и AppendJustReleasedKeys: они вернут разом все клавиши, нажатые или отпущенные в этом тике, — удобно для записи демо и отладки ввода. На этом границы известны, и клавиатура складывается в аккуратный слой из трёх функций и одного правила.