Ошибка DllNotFoundException: cardboard_api при запуске собранного проекта или чёрный экран вместо стереоскопической картинки — типичные признаки того, что Google Cardboard SDK подключён к проекту неправильно: либо не импортированы нативные библиотеки, либо не выбран нужный плагин рендеринга. Эта статья разбирает, как устроен SDK, как корректно добавить его в проект на Unity или в нативное Android-приложение и какие настройки проверить, если VR-режим не запускается.
Google Cardboard SDK — это открытый инструментарий от Google для создания простых VR-приложений под смартфоны, вставляемые в картонный или пластиковый держатель с линзами. Исходный код проекта опубликован на GitHub, а поддержка со стороны Google сейчас ограничена: развитием занимается сообщество. Это важно учитывать при выборе SDK для коммерческого проекта.
Что умеет Google Cardboard SDK
SDK выполняет узкий, но критичный набор задач: без него смартфон не сможет корректно разделить картинку на два глаза и компенсировать искажения линз. Основные функции:
- 🎯 Стереоскопический рендеринг — разделение кадра на левый и правый каналы с учётом межзрачкового расстояния.
- 🔍 Коррекция дисторсии линз — искажение изображения так, чтобы через линзы шлема оно выглядело ровным.
- 📱 Трекинг головы — чтение данных гироскопа и акселерометра для поворота виртуальной камеры.
- 👆 Обработка ввода — регистрация нажатия кнопки шлема (магнитной, проводящей или экранной).
- ⚙️ Профили устройств — подстройка параметров под конкретный шлем через QR-код.
Чего SDK не делает: позиционного трекинга в пространстве, поддержки контроллеров с шестью степенями свободы и пасsthrough-режима. Для этого нужны платформы уровня ARCore или полноценные VR-системы.
Установка SDK в проект Unity
Самый распространённый путь — интеграция через Unity, поскольку Google публикует Cardboard XR Plugin именно для этого движка. Плагин распространяется через пакетный менеджер как tarball или через Git-ссылку на репозиторий. Конкретная ссылка и версия меняются, поэтому актуальный адрес берите из официального репозитория googlevr/cardboard на GitHub.
Общий порядок действий выглядит так:
- 📦 Откройте
Window → Package Managerи добавьте пакет черезAdd package from git URLили из локального архива. - 🔧 Переключите платформу сборки на Android в
File → Build Settings. - 🧩 В настройках плеера задайте минимальную версию Android, указанную в документации плагина, и включите нужный графический API.
- 🎮 Добавьте в сцену камеру и скрипт отслеживания головы из примеров SDK (обычно это объект с компонентом трекинга).
☑️ Проверка перед первой сборкой Cardboard-проекта
После импорта плагина обязательно откройте демо-сцену из папки Samples пакета и соберите её на устройство первой. Если демо работает, а ваша сцена — нет, проблема в вашей конфигурации, а не в SDK.
Нативная интеграция для Android без Unity
Для приложений, написанных на Kotlin или Java с рендерингом через OpenGL ES, SDK подключается как нативная библиотека. Здесь потребуется собрать или подключить артефакты из репозитория Cardboard и самостоятельно реализовать цикл рендеринга: инициализация, получение матриц для каждого глаза, отрисовка сцены дважды и передача текстуры на искажение.
Этот путь заметно сложнее: вы управляете жизненным циклом GL-контекста, обработкой паузы и возобновления активности, а также сменой ориентации вручную. Ошибка в любом из этих мест даёт характерные сбои — мерцание, чёрный экран или вылет при сворачивании приложения.
⚠️ Внимание: нативная интеграция требует уверенного владения OpenGL ES и NDK. Если цель — быстро проверить идею, начните с Unity-версии плагина, а не с нативной сборки.
Настройка профиля шлема и QR-коды
Каждая модель картонного шлема имеет свои параметры: расстояние между линзами, фокусное расстояние, коэффициенты дисторсии. SDK хранит эти данные в виде профиля, который передаётся через QR-код, напечатанный на шлеме или сгенерированный производителем.
При первом запуске приложение предлагает отсканировать код. Если шлем без кода, используется профиль по умолчанию — картинка при этом может выглядеть искажённой или вызывать дискомфорт. Неправильный профиль линз — самая частая причина двоения изображения и укачивания, хотя сам SDK работает исправно.
Проверить, какой профиль активен, можно через отладочный вывод SDK. Если у вас несколько разных шлемов в тестовом парке, сканируйте QR-код заново при каждой смене устройства — профиль не подбирается автоматически.
Типичные ошибки и их устранение
Большинство проблем при работе с Cardboard SDK делятся на три группы: ошибки сборки, ошибки времени выполнения и визуальные дефекты. Таблица ниже помогает быстро сориентироваться.
| Симптом | Вероятная причина | Что проверить |
|---|---|---|
| DllNotFoundException при запуске | Нативная библиотека не включена в сборку | Настройки плагина, целевые архитектуры (ARM64) |
| Чёрный экран в VR-режиме | Неверный графический API или камера без трекинга | Graphics API в Player Settings, компоненты камеры |
| Двоение и искажение картинки | Неподходящий профиль шлема | Сканирование QR-кода конкретного шлема |
| Дрейф изображения без движения головы | Некалиброванный гироскоп устройства | Тест на другом смартфоне, перезапуск приложения |
| Вылет при сворачивании приложения | Некорректная обработка паузы GL-контекста | Обработчики жизненного цикла активности |
Отдельно стоит сказать про архитектуры процессора. Современные требования Google Play к 64-битным сборкам означают, что в настройках сборки должна быть включена ARM64; если собрать только 32-битный вариант, приложение может не пройти публикацию или работать не на всех устройствах.
⚠️ Внимание: не меняйте параметры дисторсии линз вручную в коде «на глаз» — это почти гарантированно приведёт к дискомфорту пользователей. Используйте профили, сгенерированные официальным генератором QR-кодов для шлемов.
Сравнение с альтернативами
Cardboard SDK — не единственный способ сделать мобильный VR. Выбор зависит от задачи:
- 🥽 Cardboard SDK — минимальный порог входа, работает почти на любом смартфоне, но только поворот головы без позиционного трекинга.
- 🌐 WebXR — VR прямо в браузере без установки приложения, подходит для демо и маркетинговых проектов.
- 🎮 OpenXR / платформенные SDK — полноценный VR с контроллерами, но требуется совместимая гарнитура.
Если проект образовательный, музейный или рассчитан на массовую раздачу дешёвых шлемов, Cardboard остаётся рабочим выбором. Для игр со сложным взаимодействием его возможностей недостаточно.
Почему Google почти не развивает Cardboard SDK
Компания перевела фокус на ARCore и передала репозиторий Cardboard в режим поддержки сообществом. Код открыт, форки существуют, но новых функций от Google ждать не стоит — закладывайте это в долгосрочные планы проекта.
Публикация и требования Google Play
Приложения с Cardboard SDK публикуются как обычные Android-приложения, но есть нюансы. В манифесте стоит корректно указать используемые сенсоры — гироскоп и акселерометр, — чтобы маркет не предлагал установку на устройства без них. Если VR-режим основной, имеет смысл пометить приложение соответствующей категорией.
Перед релизом протестируйте сборку минимум на нескольких устройствах с разными экранами и версиями Android: качество трекинга головы сильно зависит от сенсоров конкретного смартфона, и на бюджетных моделях дрейф может быть заметно сильнее.
Часто задаваемые вопросы
Поддерживается ли Google Cardboard SDK сейчас?
Google перевела проект в открытый код и практически не выпускает обновлений. SDK остаётся рабочим, исходники доступны на GitHub, но новые функции и исправления зависят от сообщества. Для новых коммерческих проектов оценивайте это как риск.
Можно ли использовать Cardboard SDK без Unity?
Да, существует нативная версия для Android с рендерингом через OpenGL ES. Однако она требует самостоятельной реализации цикла рендеринга и обработки жизненного цикла активности, что заметно сложнее интеграции через Unity-плагин.
Почему картинка двоится, хотя приложение запускается без ошибок?
Наиболее вероятная причина — несоответствие профиля шлема: отсканируйте QR-код именно вашего держателя с линзами. Если код отсутствует, попробуйте сгенерировать профиль через генератор параметров шлема или протестируйте приложение с другим шлемом.
Работает ли Cardboard SDK на iOS?
Исторически SDK поддерживал iOS, и в открытом репозитории сохранились соответствующие компоненты. Однако актуальность iOS-сборки и её совместимость с новыми версиями Xcode нужно проверять в репозитории проекта — гарантий поддержки нет.
Нужен ли интернет для работы VR-приложения на Cardboard?
Нет, сам SDK работает полностью офлайн: трекинг головы и рендеринг выполняются локально на устройстве. Интернет может понадобиться только вашему приложению для загрузки контента.