Введение: зачем размещать Unity-игру на Hugging Face Space
Hugging Face Space - это бесплатный хостинг для интерактивных веб-приложений, который изначально создавался для демонстрации ML-моделей, но отлично подходит и для WebGL-игр. Вы получаете публичный URL, автоматическую пересборку при пуше в Git и доступ к сообществу разработчиков. Для Unity-разработчика это способ показать интерактивное демо без аренды сервера, настройки Nginx и покупки домена.
Процесс публикации состоит из четырёх шагов: настройка Unity-проекта под WebGL, создание Space с шаблоном Static HTML, загрузка файлов сборки через Git и Git-LFS, проверка работоспособности. Всё это занимает 15–20 минут при условии, что Unity и Git уже установлены. Ниже - точная последовательность действий с командами и настройками.
Если вы уже работали с Hugging Face, например, загружали Jupyter-ноутбуки на Hub, логика Space покажется знакомой: репозиторий, пуш, автоматический деплой. Разница только в том, что здесь нет Python-окружения, а есть статический веб-сервер, который отдаёт ваши HTML, JS и WASM-файлы.
Для тех, кто параллельно осваивает генерацию сайтов через AI-агентов, этот же подход применим и к статическим лендингам: создание сайта через Codex и GPT-5.6 использует похожую схему «сборка → загрузка → публикация».
Подготовка Unity-проекта к сборке WebGL
Перед созданием Space нужно подготовить Unity-проект. Откройте Build Settings через File → Build Settings, выберите платформу WebGL и нажмите Switch Platform. Unity перекомпилирует ассеты под браузерный формат. Это обязательный шаг: без переключения платформы сборка не создаст нужные файлы.
Далее проверьте, что в проекте нет зависимостей, несовместимых с WebGL. Некоторые нативные плагины, работающие в Windows-билдах, не компилируются под WebGL. Если проект использует такие плагины, Unity выдаст ошибку на этапе сборки. Решение - найти WebGL-совместимую альтернативу или исключить плагин из сборки через директивы условной компиляции.
Установка Hugging Face WebGL Template
Стандартный шаблон Unity для WebGL генерирует index.html с определённой структурой загрузчика. Hugging Face Space ожидает, что index.html находится в корне репозитория и корректно ссылается на Build-файлы. Специальный шаблон Hugging Face WebGL Template адаптирует генерируемый HTML под эту структуру.
Шаблон доступен на GitHub. Скачайте репозиторий, найдите папку с шаблоном и скопируйте её в проект Unity по пути Assets/WebGLTemplates/. После этого откройте Player Settings → Resolution and Presentation → WebGL Template и выберите установленный шаблон из выпадающего списка. Unity будет использовать его при каждой сборке.
Если вы не хотите использовать сторонний шаблон, можно обойтись стандартным, но тогда после сборки придётся вручную править index.html: убирать лишние пути, исправлять ссылки на Build-файлы. Шаблон Hugging Face экономит эти правки.
Отключение сжатия в настройках сборки
Unity по умолчанию включает сжатие для WebGL-сборки: Brotli или Gzip. Файлы с расширениями .br или .gz загружаются быстрее, но Hugging Face Static HTML Space не всегда корректно обрабатывает такие файлы без дополнительной настройки сервера. Итог - белый экран и ошибка загрузки.
Откройте Player Settings → Publishing Settings → Compression Format и установите значение Disabled. После этого Unity будет генерировать несжатые файлы .data, .wasm и .js. Они больше по размеру, но гарантированно загружаются в Space. Для небольших демо разница в объёме некритична: типичная сцена без тяжёлых ассетов весит 10–30 МБ.
Создание Space на Hugging Face
Войдите в аккаунт на huggingface.co. Нажмите кнопку New Space в правом верхнем углу. В открывшейся форме укажите название Space, выберите видимость (Public или Private) и в списке SDK выберите Static HTML. Этот шаблон создаёт репозиторий с базовым index.html и не требует Python или Node.js.
Название Space станет частью URL: huggingface.co/spaces/ваш-username/название-space. Для публичного демо выбирайте Public, чтобы ссылкой можно было делиться. Private Space доступен только вам и приглашённым пользователям.
После создания Space Hugging Face покажет страницу с инструкцией по клонированию репозитория. Склонируйте его локально:
git clone https://huggingface.co/spaces/ваш-username/название-space
cd название-spaceВнутри уже есть файл index.html и README.md. Их можно оставить или заменить на файлы Unity-сборки.
Загрузка файлов сборки через Git и Git-LFS
WebGL-сборка Unity содержит файлы, которые превышают лимит GitHub и Hugging Face на обычные Git-объекты (100 МБ). Файлы .data и .wasm часто весят 20–80 МБ, а при использовании тяжёлых ассетов - больше 100 МБ. Git-LFS решает эту проблему: большие файлы хранятся отдельно, а в репозитории остаются только указатели.
Настройка Git-LFS для больших файлов
Установите Git-LFS, если он ещё не установлен. На Ubuntu это пакет git-lfs, на macOS - brew install git-lfs, на Windows - установщик с git-lfs.com. После установки выполните в репозитории:
git lfs install
git lfs track "*.data"
git lfs track "*.wasm"
git lfs track "*.unityweb"
git lfs track "*.js"Команда git lfs track создаёт или обновляет файл .gitattributes. Проверьте его содержимое: в нём должны быть перечислены все отслеживаемые расширения. Файл .gitattributes нужно закоммитить вместе с остальными файлами.
Если вы забудете настроить Git-LFS до первого пуша, большие файлы попадут в обычный Git и Hugging Face отклонит пуш с ошибкой о превышении лимита. В этом случае нужно выполнить git lfs migrate import, чтобы перенести уже добавленные файлы в LFS.
Копирование файлов сборки и пуш
После сборки Unity создаёт папку Build (или папку с названием, которое вы указали в Build Settings). Внутри находятся index.html, папка Build с файлами .data, .wasm, .js и папка TemplateData с CSS и логотипами. Скопируйте содержимое этой папки в корень репозитория Space:
cp -r путь/к/Unity/Build/* .Убедитесь, что index.html лежит в корне, а не во вложенной папке. Hugging Face Static HTML Space ищет index.html именно в корне. Если файл окажется в подпапке, Space покажет 404.
Закоммитьте и запушьте изменения:
git add .
git commit -m "Add Unity WebGL build"
git pushПосле пуша Hugging Face автоматически пересоберёт Space. Обычно это занимает 1–3 минуты. Статус можно отслеживать на странице Space: индикатор Building сменится на Running.
Проверка и устранение неполадок
Откройте URL Space в браузере. Если игра загрузилась и реагирует на ввод - публикация успешна. Если видите белый экран или ошибку, откройте консоль браузера (F12 → Console) и проверьте, какие запросы падают.
Частые ошибки и их решение
404 на файлах Build. Причина - неверные пути в index.html или файлы лежат не в корне. Проверьте, что index.html ссылается на Build/файл.data, а не на ./Build/файл.data с лишней точкой. Если вы использовали стандартный шаблон Unity, пути могут быть относительными с подпапками. Исправьте ссылки в index.html или пересоберите с Hugging Face WebGL Template.
Белый экран без ошибок. Частая причина - включённое сжатие. Проверьте Player Settings → Publishing Settings → Compression Format. Если стоит Brotli или Gzip, пересоберите с Disabled и загрузите файлы заново.
Файлы не загружаются через LFS. Если в репозитории файлы .data отображаются как текстовые указатели (размер несколько сотен байт), а не бинарные данные, Git-LFS не сработал. Выполните git lfs install и git lfs track заново, затем git add .gitattributes и git commit. Если файлы уже в истории, используйте git lfs migrate import.
Ошибка CORS. Возникает, если index.html пытается загрузить ресурсы с другого домена. В Static HTML Space все файлы должны загружаться с того же домена. Проверьте, что в HTML нет абсолютных ссылок на localhost или file://.
Если вы параллельно работаете с Jupyter-ноутбуками на Hugging Face Hub, принцип отладки похож: Jupyter-ноутбуки на Hugging Face Hub тоже требуют проверки путей и корректной загрузки файлов.
Заключение
Публикация Unity-игры в Hugging Face Space сводится к четырём действиям: переключить платформу на WebGL и отключить сжатие, создать Space с шаблоном Static HTML, настроить Git-LFS для больших файлов, скопировать сборку в корень репозитория и запушить. После этого Space автоматически развернёт игру и даст публичную ссылку.
Этот способ подходит для демо, прототипов, портфолио и тестирования игровых механик. Для продакшена с высокой нагрузкой потребуется отдельный CDN и серверная инфраструктура, но для показа сообществу Hugging Face Space закрывает задачу полностью.
Если вы экспериментируете с AI-генерацией игрового кода, обратите внимание на VibeGame - декларативный игровой движок для разработки с помощью ИИ. Он решает проблему деградации кода при росте проекта, что актуально и для Unity-сборок, генерируемых нейросетями.