@coverpixi/plugin-platform

Игровые площадки за одним контрактом: реклама, облачные сохранения, рекорды, покупки. Плагин для Coverpixi.

npx coverpixi add platform

Зачем

Игра не должна знать, где она запущена. Она знает ctx.platform — один и тот же набор вызовов на Яндекс Играх, во ВКонтакте и на дев-сервере:

const reward = await ctx.platform.ads.rewarded()
if (reward.ok) grantExtraLife()

Перевод на язык конкретного SDK живёт в адаптере — одном файле на площадку. Без этого вызовы SDK расползаются по экранам, и вторая площадка превращается в форк проекта.

Сборка под площадку

Площадка выбирается на этапе сборки, и в бандл попадает ровно один адаптер — сборка под Яндекс не содержит кода ВКонтакте:

npm run build:yandex   # dist/yandex
npm run build:vk       # dist/vk
npm run build          # dist/local — заглушка для разработки

Команды добавляются в package.json при установке плагина.

Что умеет

| Область | Вызовы | |---|---| | ads | interstitial(), rewarded(), showBanner(), hideBanner() | | leaderboards | submit(), top(), player() | | payments | catalog(), purchase(), pending(), consume() | | social | share(), invite(), rate(), addShortcut(), addFavorite() | | gameplay | start(), stop() — границы активного геймплея | | — | player, environment, supports(), signIn(), serverTime() |

Сохранения живут в ядре (ctx.storage); плагин подменяет им бэкенд облаком площадки, сохраняя локальную копию подложкой. Игра без плагина обязана уметь сохраняться — поэтому владеть хранилищем площадка не вправе.

Отказ — это значение, а не исключение

const result = await ctx.platform.leaderboards.top('main', 10)
if (result.ok) rows = result.value

Причина отказа нужна интерфейсу: unsupported — площадка такого не умеет, кнопку можно не рисовать вообще; unavailable — умеет, но не сейчас (кулдаун); cancelled — игрок закрыл окно сам, и сообщать ему не о чем; error — SDK упал, и это уже в консоли. Сбой площадки не роняет кадр.

Пауза под рекламой

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

Межстраничные ограничены кулдауном, отсчёт идёт и от загрузки игры — первый ролик не выскочит на старте.

Поддержка площадок

| Возможность | local | yandex | vk | |---|---|---|---| | Реклама: межстраничная, за награду, баннер | оверлей с отсчётом | да | да | | Облачные сохранения | нет, localStorage | да | да, значение ≤ 4096 символов | | Рекорды | в localStorage | да | только отправка, с окном площадки | | Покупки | фиктивный каталог | да | только покупка | | Поделиться, пригласить | лог в консоль | нет | да | | Оценить игру, ярлык | лог в консоль | да | ярлык |

local — не пустышка: реклама там оверлей, который действительно ставит игру на паузу, у ролика за награду есть кнопка досрочного закрытия. Без неё половина игры проверялась бы только на прод-сборке. Она же запасной вариант: если SDK площадки не поднялся, игра переключается на заглушку и остаётся играбельной.

vk — это ВКонтакте (игры и мини-приложения поверх VK Bridge), не VK Play: у той свой SDK.

Настройка

// coverpixi.config.ts
platform: {
  interstitialCooldown: 60,   // секунд между межстраничными
  storagePrefix: 'my-game',   // префикс ключей локальных сохранений
}

Новая площадка

Скопировать adapters/template.ts, заполнить, добавить строку в adapters/registry.ts и создать .env.<имя> с VITE_PLATFORM=<имя>. Реализовывать нужно только то, что площадка умеет: отсутствующий метод честнее заглушки — игра увидит unsupported и спрячет кнопку.

Лицензия

MIT