Game Porting Toolkit 4: среда 2026 и первый playable

Первая ошибка команды — называть переносом сам факт, что исходный Windows-файл запускается в оценочной среде. Это только оценка совместимости, а не нативная сборка для macOS и тем более не готовый продукт для пользователей.

Перед настройкой следует выбрать один из трёх результатов:

• Оценка совместимости — запускается неизменённая Windows-сборка, фиксируются запуск, первый кадр, визуальные ошибки, ввод и приблизительное поведение рендеринга.
• Нативный перенос — код, окна, ввод, графический API, шейдеры, звук и платформенные сервисы адаптируются под Apple-платформы.
• Подготовка к выпуску — добавляются подпись, упаковка, тестирование на целевых устройствах, обработка ошибок, производительность и пользовательские сценарии.

Такое разделение важно из-за нескольких скрытых затрат.

Во-первых, совместимый запуск может скрывать ошибки, которые проявятся только в нативном Metal-пути: неверные состояния ресурсов, отличия в синхронизации, ошибки преобразования шейдеров или некорректную работу с drawable.

Во-вторых, Windows-ориентированный ввод редко переносится без проверки. XInput, DirectInput, Raw Input и другие подсистемы требуют сопоставления с Game Controller API и отдельной проверки раскладки, паузы, полноэкранного режима и поведения при отключении контроллера. Официальный набор навыков Game Porting Toolkit 4 отдельно включает работу с контроллерами и настройкой окна macOS.

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

Перед началом полезно отметить:

• [ ] Цель текущего этапа записана одним предложением.
• [ ] Есть Windows-сборка, которую можно запустить без изменений.
• [ ] Сохранены reference-кадры и сценарий, по которому сравнивается результат.
• [ ] Определены ответственные за код, графику, ввод и приёмку.
• [ ] Секреты отделены от исходного дерева и локальных временных файлов.
• [ ] Команда договорилась, что «запускается» не равно «прошёл первый playable».

Какую среду требует Game Porting Toolkit 4?
Официальный README указывает Apple Silicon Mac, macOS 27, Xcode 27 и Game Porting Toolkit 4. При этом страница загрузки, статус beta или release candidate и конкретные команды могут измениться, поэтому перед установкой нужно сверить официальную документацию, а не копировать старую инструкцию из форума. Xcode 27 Beta в текущих заметках Apple также имеет отдельные требования и ограничения, связанные с тестовым статусом. (страница Game Porting Toolkit для разработчиков)

Среду следует создавать не на основном рабочем компьютере, а на отдельном экземпляре, где можно удалить каталог, вернуть состояние снапшота или полностью переустановить зависимости. Это особенно важно для Game Porting Toolkit 4, потому что одновременно участвуют macOS, Xcode, командные инструменты, репозиторий с подмодулями, Agent и графические утилиты.

Порядок действий:

1. Запишите версии и источник каждой зависимости

В отдельном файле зафиксируйте:

• версию macOS;
• версию Xcode;
• состояние Command Line Tools;
• редакцию Game Porting Toolkit 4;
• commit официального репозитория;
• используемый Agent;
• дату проверки;
• способ возврата к чистому состоянию.

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

2. Клонируйте официальный репозиторий вместе с подмодулями

В README Apple прямо указано, что репозиторий нужно клонировать с подмодулями, чтобы корректно получить Metal-cpp и связанные материалы. Базовая команда выглядит так:

git clone --recurse-submodules https://github.com/apple/game-porting-toolkit.git

Если репозиторий уже был склонирован без подмодулей, официальный README предлагает инициализировать их отдельно:

git submodule update --init --recursive

После этого следует проверить наличие каталога metal-cpp, примеров и каталога навыков. Сам факт успешного клонирования не подтверждает полноту дерева: отсутствие подмодуля может обнаружиться только на этапе сборки или Agent-разведки.

3. Разделите рабочие данные

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

Минимальная структура может быть такой:

project/
  source/
  assets/
  build/
  captures/
  reports/
  secrets-outside-repository/

В репозиторий не следует добавлять .gputrace, временные дампы, токены и локальные конфигурации Agent. Файл состояния портирования также нужно включать в процедуру резервирования: официальный workflow использует каталог .porting/ для отчётов, целей, handoff-записей и памяти проекта.

С какого этапа начинать перенос Windows-игры на Mac?
Начинать следует с неизменённой Windows-сборки в оценочной среде, а не с массовой замены DirectX-вызовов. Цель первого запуска — получить список блокеров, а не добиться красивой картинки любой ценой.

Apple описывает оценочную среду как способ проверить существующий Windows-бинарник на Apple Silicon, оценить переносимость графики и проверить преобразование шейдеров. В этой же фазе доступны Metal Performance HUD, GPU capture и Metal System Trace, поэтому базовую диагностику можно начать до полной нативной адаптации. (официальное описание Game Porting Toolkit)

В отчёт базовой оценки следует внести:

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

Однократное значение FPS нельзя превращать в универсальное утверждение о производительности. Даже официальный материал Apple описывает оценку как способ получить baseline estimate, а не как окончательный бенчмарк для всех Mac и всех игр.

На этом этапе полезна следующая отметка:

• [ ] Сохранен исходный Windows-бинарник.
• [ ] Записан commit, из которого он собран.
• [ ] Сняты reference-кадры из тех же сцен.
• [ ] Ошибки разделены на запуск, графику, ввод, звук и платформенные сервисы.
• [ ] Есть хотя бы один повторяемый сценарий запуска.
• [ ] GPU-захват и логи сохранены с датой и названием сборки.

Game Porting Toolkit 4 добавляет официальный репозиторий с навыками для кодирующих Agent. Он содержит экспертные знания по Metal 4, MetalFX, преобразованию шейдеров, ресурсам, синхронизации, окну, контроллерам и GPU-отладке, а также workflow-навыки для разведки, планирования, выполнения, проверки и передачи результата. (официальный справочник навыков Game Porting Toolkit)

Как устанавливаются навыки Agent для Game Porting Toolkit 4?
Команда выбирает один поддерживаемый вход — Claude Code, Codex CLI или Gemini CLI — и использует способ, указанный в официальном README. Например, для Claude Code README приводит регистрацию marketplace и установку плагина:

/plugin marketplace add apple/game-porting-toolkit
/plugin install game-porting-skills@game-porting-toolkit

Для Codex CLI предусмотрена регистрация marketplace и добавление плагина:

codex plugin marketplace add https://github.com/apple/game-porting-toolkit
codex plugin add game-porting-skills@game-porting-toolkit

Для Gemini CLI используется установка расширения из локального каталога:

gemini extensions install /path/to/game-porting-toolkit/game-porting-skills

Эти команды нужно сверять непосредственно с текущим README: изменение структуры marketplace или каталога навыков может сделать старую инструкцию непригодной.

После установки Agent не следует сразу просить «перенести всю игру». Сначала нужно запустить discovery-процесс и проверить, что отчёт содержит:

• графический API и точки его использования;
• платформенные зависимости;
• систему сборки;
• обработку окна и ввода;
• шейдерный pipeline;
• загрузку ресурсов;
• аудио и сетевые сервисы;
• проблемные участки, подтверждённые логами или захватами;
• список неизвестных мест, требующих ручной проверки.

Затем команда формулирует одну цель, например: «получить минимальное окно с одним стабильным рендер-проходом». Одна цель разбивается на небольшие milestones, каждый из которых должен завершаться проверкой, commit и handoff-записью.

К середине проекта становится видно, что выбор между локальным и облачным Mac определяется не только производительностью. Важнее частота интерактивной GPU-отладки, размер проекта, параллельность Agent-сессий, необходимость физического контроллера и ответственность за обслуживание среды.

Можно ли завершить тестирование переноса игры на облачном Mac?
Да, если задача ограничена базовой оценкой, сборкой, Agent-разведкой, повторяемыми GPU-захватами и проверкой первого playable без физической периферии. Но удалённый рабочий стол не должен использоваться как доказательство реальной игровой плавности: задержка передачи изображения, компрессия и частота обновления могут изменить субъективную оценку.

Для Windows-команд Apple также документирует удалённую сборку и отладку macOS-версии из Visual Studio на PC. В таком сценарии нужно отдельно проверить SSH, VNC или Remote Management, сетевые правила и доступ к целевому Mac. Документация Apple указывает, что для удалённой работы могут потребоваться Remote Login, Remote Management и разрешения firewall. (документация Apple по удалённой сборке macOS-игры)

Практические рекомендации по подготовке удалённой среды можно сверить в руководстве по подготовке облачного Mac, а условия временного доступа — на странице аренды Mac для тестовой среды. Перед передачей репозитория необходимо проверить, кто отвечает за обновления, очистку диска, восстановление снапшота и удаление секретов.

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

На этом этапе не следует одновременно переносить все подсистемы. Приоритет обычно такой:

1. создать минимальное окно;
2. инициализировать графический контекст;
3. вывести простой тестовый объект;
4. проверить командную очередь и представление drawable;
5. загрузить один контролируемый ресурс;
6. получить повторяемый GPU-захват;
7. только после этого подключать сложные материалы, постобработку и игровые сцены.

Особое внимание требуется уделить четырём классам ошибок:

• шейдеры — неправильное преобразование HLSL, несовместимые типы, отсутствующая информация для отладки;
• ресурсы — неверные форматы, жизненный цикл буферов, residency и таблицы дескрипторов;
• синхронизация — ошибки барьеров, fence, event и переходов состояний;
• представление кадра — CAMetalLayer, vsync, frame pacing, полноэкранный режим и обработка изменения размера окна.

Официальный справочник навыков Game Porting Toolkit 4 содержит отдельные разделы по Metal Shader Converter, Metal 4, ресурсам, синхронизации, drawable presentation, validation, gpucapture и gpudebug. Это полезнее, чем просить Agent дать обобщённый совет без привязки к захвату и конкретному месту ошибки.

Для каждого исправления нужно сохранять:

• исходный лог;
• GPU-захват до изменения;
• commit;
• повторный захват;
• вывод о том, исчезла ли проблема;
• оставшиеся ограничения.

При удалённой работе команда должна отдельно фиксировать качество изображения в захвате и качество передачи рабочего стола. Эти параметры нельзя смешивать: плохая картинка в VNC не обязательно означает плохой рендеринг игры, а плавный удалённый интерфейс не подтверждает реальную частоту кадров приложения.

Что проверять в первом playable?
Первый playable следует принимать только после прохождения минимального игрового сценария от запуска до управляемого действия, а не после появления главного меню.

Минимальный чек-лист:

• [ ] Чистая среда восстанавливается по записанной инструкции.
• [ ] Сборка запускается повторно после очистки кэша.
• [ ] Игра проходит стартовый экран или меню.
• [ ] Загружается выбранная тестовая сцена.
• [ ] Камера, персонаж или другой основной объект реагируют на ввод.
• [ ] Проверены клавиатура, мышь и целевой контроллер.
• [ ] Основные текстуры, материалы, освещение и глубина отображаются корректно.
• [ ] Нет постоянного чёрного экрана, случайных пропаданий объектов и очевидного мерцания.
• [ ] Есть базовый звук, если он входит в текущую цель.
• [ ] Сохраняется хотя бы один диагностический GPU-захват.
• [ ] Известные блокеры записаны с владельцем и следующим действием.
• [ ] Windows reference-сценарий сопоставлен с результатом на Mac.
• [ ] Commit, отчёт и handoff-файл переданы следующему участнику.

После этого команда должна выбрать дальнейшую модель:

• Если первый playable нужен на короткий срок, Agent-сессии идут параллельно, а интерактивная GPU-отладка выполняется не каждый день — продолжайте в облачной среде.
• Если проект требует регулярного ручного захвата, настройки шейдеров и длительных сессий, выбирайте постоянный локальный Apple Silicon Mac.
• Если сборки можно выполнять удалённо, но графику нужно проверять без сетевой задержки, используйте двойной контур: облачная среда для оценки и сборок, локальная — для критической отладки.
• Если команда не может определить владельца обновлений и восстановления, не расширяйте парк машин: сначала опишите процедуру среды и повторите чистую сборку.

Покупка Mac для всей команды до базовой оценки создаёт несколько реальных недостатков: капитал замораживается до подтверждения переносимости, машины простаивают между milestones, а ответственность за версии macOS, Xcode 27, кэши и восстановление полностью ложится на команду. При удалённой работе добавляется ещё одна проблема — физический компьютер не всегда доступен тому инженеру, которому он нужен именно сейчас.

Аренда Mac в NUKCLOUD логичнее для короткой проверки, нескольких параллельных веток и проектов, где решение о выпуске ещё не принято. Если команда уже прошла первый playable и перешла к длительной графической оптимизации с ежедневными захватами, собственный Mac может дать более предсказуемую интерактивную работу. Для промежуточного варианта можно оставить облачную среду как чистый стенд, а локальную машину использовать для ручной отладки и проверки периферии.

Если отдельного Apple Silicon Mac пока нет, команде стоит начать с условий и вариантов подключения NUKCLOUD, выбрать краткосрочную тестовую среду и зафиксировать критерии остановки аренды: завершённая базовая оценка, первый кадр, первый playable или решение о покупке. Такой порядок не заменяет полноценную производственную инфраструктуру, но позволяет проверить техническую состоятельность переноса до того, как команда начнёт оплачивать постоянный парк устройств.