Установка и первый игровой цикл

Начнём с команды, которая и есть вся установка: go get github.com/hajimehoshi/ebiten/v2@latest. Суффикс /v2 в пути — не украшение, а правило Go-модулей для второй мажорной версии: импортировать вы будете ровно этот путь, и компилятор не перепутает старую ветку с новой. Движку нужен свежий Go, и требование растёт со временем: ветка 2.8 просила Go 1.22, а документация актуальных релизов требует Go 1.25 и новее — проверьте версию командой go version, прежде чем ругаться на странные ошибки компиляции.

Вторая тема — компилятор C, вокруг которой накопилось много устаревших советов. Исторически десктопные сборки Ebitengine шли через cgo, и на Windows вам был нужен gcc из MSYS2, на macOS — командные инструменты Xcode, на Linux — компилятор и заголовки системных библиотек. С версии 2.10 документация сообщает важное: десктопные сборки (Windows, macOS, Linux, FreeBSD) собраны в чистом Go, и C-компилятор для них больше не нужен — cgo остался требованием мобильных платформ. Если вы найдёте инструкцию 2023 года, которая заставляет ставить MinGW — она устарела: для актуальных версий достаточно Go и, на Linux, пакетов графической среды. Сделайте go mod tidy после первого импорта, чтобы go.mod и go.sum пришли в порядок, — стандартная гигиена любого Go-проекта. Если сам Go для вас пока в новинку, заложите фундамент в базовом курсе, а затем возвращайтесь сюда.

Теперь главное — что происходит, когда вы запустили программу. RunGame забирает управление и начинает крутить цикл: Update вызывается каждый тик, по умолчанию 60 раз в секунду, и движок гарантирует, что между двумя соседними вызовами проходит ровно 1/60 секунды — независимо от того, какой у вас монитор и как быстро процессор. Draw вызывается каждый кадр, и его частота определяется частотой обновления монитора: на 60-герцовом дисплее это те же 60 кадров в секунду, на 120-герцовом — вдвое чаще, хотя тики по-прежнему идут с частотой 60. Первым кадром движок обещает порядок: Layout вызывается до первого Update, а Update — хотя бы раз до первого Draw, поэтому состояние игры всегда готово к отрисовке.

Из этого контракта следует правило, которое записано прямо в документации метода Draw: не кладите в него игровую логику. Draw — функция от картинки, и его частота зависит от железа пользователя; логика, привязанная к кадрам, ускорится на игровом мониторе и замедлится на ноутбуке. Правильная привычка: Update меняет числа, Draw только переводит числа в пиксели. Если 60 тиков вам мало — скажем, для точной физики — есть ebiten.SetTPS со значением по частоте; а фактическую частоту тиков и кадров в живой программе показывают ebiten.ActualTPS и ActualFPS. Оба замера — для отладки: на них нельзя строить механику, только смотреть глазами.

Функция ebiten.RunGame(game) — точка невозврата: она блокирует goroutine main до закрытия окна, и любой код после неё выполнится только при завершении игры. Вызывать RunGame в одном процессе можно один раз; документация прямо запрещает повторные вызовы. Если Update вернёт обычную непустую ошибку, цикл остановится, и RunGame вернёт эту же ошибку — это штатный способ падать с осмысленным сообщением, например когда не загрузился ассет. А для добровольного выхода — скажем, по нажатию Escape — есть особое значение ebiten.Termination: верните его из Update, игра остановится, но RunGame вернёт nil, и вам не придётся отличать «игрок вышел» от аварии.

Семья функций запуска исторически менялась, и в чужом коде вы встретите три стиля. В первой версии движка вход был функцией ebiten.Run с замыканиями: она принимала два колбэка, ширину, высоту, масштаб и заголовок окна — на конце первой ветки её пометили устаревшей в пользу RunGame. Во второй версии основной вход — RunGame(game) из этого урока, а окно настраивают пакетными функциями вроде SetWindowSize и SetWindowTitle до запуска, как в каркасе выше. А с версии 2.6 рядом появился RunGameWithOptions(game, options), где в структуре опций настраивают графическую библиотеку, прозрачность окна и однопоточный режим: если вы не задаёте таких флагов, простого RunGame достаточно. Таблица ниже сводит всё семейство одной строкой на функцию.

Сценарий, который сбивает каждого второго: вы запускаете игру, переключаетесь в браузер посмотреть документацию — и таймер в логах замирает. Это не баг и не зависание: по умолчанию Update и Draw не вызываются, пока окно Ebitengine не в фокусе. Движок экономит ресурсы системы — нечего тикать игре, которую никто не видит. Для отладки это изматывает: вы смотрите на лог и не понимаете, почему счётчик стоит.

Поведение управляется функцией ebiten.SetRunnableOnUnfocused: передайте true до RunGame, и игра продолжит тикать даже в фоне. Здесь стоит быть аккуратным с обещаниями: игра, которая считает ресурсы в фоновом режиме, может раздражать пользователя и сливать батарею на ноутбуке. Разумная стратегия — держать runnable-on-unfocused выключенным в релизе и включать по флагу отладки, когда нужно наблюдать за логами при свёрнутом окне. Соседняя настройка — InitUnfocused в RunGameOptions: запустить игру сразу в нефокусном окне, что полезно для демо и оверлеев. Запомните эту пару «замерло — проверь фокус», она сэкономит вам один бессмысленный вечер: к вводу и паузам мы вернёмся в уроках про клавиатуру и сцены.

Скажем честно про границы урока: весь код этой главы для запуска нуждается в локальном Go и графическом окне — песочница сайта не умеет открывать окна и рисовать спрайты, да и Ebitengine в браузерную сборку интерпретатора не влезет. Но сама суть цикла — числа, которые меняются 60 раз в секунду, — чистая математика, и она считается прямо на странице: тематическая программа в песочнице сайта эмулирует тики и подсчитывает шаги, как это сделал бы Update. Прогоните её до того, как соберёте настоящий проект: почувствовать ритм 1/60 секунды на числах полезнее, чем вчитываться в чёрное окно. Дальше по курсу мы рисуем: третий урок покажет, как Layout превращает ваши 320 на 240 в любое окно.