@kvisaz/phaser-common

Общий переиспользуемый движковый слой для игр на Phaser 3 (стиль Kvisaz Games): массивы, коллекции, события, эффекты, вёрстка/layout, сервисы, карточные игры и game-core.

Я хочу сделать этот репозиторий тестовой площадкой для движков разных игр, тестировать игры в сторибуке без ассетов, отполировывать их до посинения, чтобы было просто потом их вставлять и натягивать скин.

Тут уже есть

• пасьянс Косынка
• пасьянс Паук
• 2048

Хочу

• утилиты для генерации карт мира
• код для большой карты мира

Документация

• Полный список что есть в библиотеке
• Layout — базовая вёрстка UI в @kvisaz/phaser-common
• GameCore — как это работает и как запустить свою мини-игру
• GameCore — идеи на будущее

Выделен из проекта как отдельная библиотека по образцу phaser-sugar. Раньше зависел от @kvisaz/phaser-sugar; сейчас все нужные утилиты (layout/Align, color, load, typeGuards, NiceTextStyle и др.) перенесены внутрь пакета, внешних runtime-зависимостей нет. Граница изолирована: внутри пакета запрещены импорты извне (кроме библиотек и внутренних модулей).

Отдельно - runGameCore из GameCore - создает обвязку со звуками, рекламой, загрузкой к которой толкьо надо подключить свой игровой компонент (класс с методом destroy() который вызывается при перезапуске)

/**
 * Запуск тестовой игры на GameCore v1
 * - config - настройки Phaser (config.phaser) и игрового ядра (ads/sound/cursor/storage и т.д.)
 * - assets - набор ассетов, которые ядро грузит в Boot-сцене
 * - events - общая шина, связывающая фичи ядра с контентом игры
 * - gameConfig - ядро кладёт конфиг игры в context.config для контента
 * - createGameContent - создаёт игровой контент (объект с destroy()):
 *   ядро регистрирует его на очистку при перезапуске сцены
 */
runGameCore<ITestEvents, ITestConfig, ITestSaveData>({
  config: testGameCoreConfig,
  assets: testAssets,
  events: new GameEventBus<ITestEvents>(),
  gameConfig: testConfig,
  createGameContent: (context) => new TestGameContent(context),
});

Тестовая игра (npm run start)

npm run start запускает самодостаточную тестовую игру на GameCore v1 из этой библиотеки (test-game/): события шины, сохранение state, fullscreen/rewarded-реклама (mock), sound mute, cursor, restart сцены и cleanup. Dev-сервер: порт 8082; деплой-сборка: npm run build:test-game → docs/test-game.

Storybook

Живая демо-среда доступна в собранной static-сборке:

• Storybook

Пересобрать демо:

npm run build-storybook

Сборка и проверки

npm install
npm run typecheck   # проверка типов
npm run build       # Vite lib mode (dist/index.mjs + dist/index.js) + генерация .d.ts
npm test            # jest
npm run storybook   # dev-сервер демо (порт 8081)

⚠️ Не создавай npm-скрипт publish — npm выполняет его повторно после публикации (двойная публикация). Для релиза используй npm run release.

Использование

Пакет рассчитан на глобальный Phaser (подключается на странице, типы — через types: ["phaser"] в tsconfig потребителя). Точка входа — src/index.ts, типы — dist/index.d.ts.

Два формата: ESM и CJS

npm run build собирает dist/ сразу в двух форматах, чтобы пакет одинаково подходил и современным, и классическим потребителям:

• dist/index.mjs — ESM (import). Подключается бандлерами и современным Node через "module"/exports.import в package.json. Даёт tree-shaking: неиспользуемые функции пакета могут быть исключены из итоговой сборки игры.
• dist/index.js — CJS (require), аналог сборки phaser-sugar. Подключается через "main"/exports.require, работает в Node и старых сборках без ESM.

Какой файл подтянется — решает потребитель (бандлер/Node) по полю exports; ручное указание пути не требуется.

Yandex SDK — не обязателен для игры

Пакет содержит крошечные обёртки над Яндекс-сервисами (≈100 строк), но игра не обязана ставить @types/ysdk или что-то ещё — это dev-зависимость пакета, в потребители не течёт.

Для игры на Яндекс-площадке — подключи на страницу sdk.js (глобальный YaGames), поставь platform.enabled: true в конфиге — SDK заработает. Для игры без Yandex — просто platform.enabled: false, всё само работает через mock/local-заглушки (реклама, сохранение, локаль). Бандл тяжелее на ≈2 KB — незаметно.

Локализация (Phaser-way, через scene.data)

Ядро жёстко выбирает язык до создания контента: ?lang= из URL → язык платформы → defaultLang (en/ru есть всегда, другие языки добавляются словарями). Выбранный язык ядро пишет в scene.data (setSceneLocale).

Игровой контент пересоздаётся вместе со сценой, поэтому читает тексты сразу при создании из контекста, без подписок и перекомпоновки:

// перевод по ключу (fallback на defaultLang)
const t = context.locale.t;
label.setText(t("btn_start"));
// ручной выбор языка из меню настроек (если нужно)
context.locale.setLanguage("en");

Подписка на onSceneLocaleChange — не обязательный слой: если какому-то компоненту нужна живая реакция на смену языка, он сам рядом с собой решает, как подписываться и как пересоздавать тексты. Движок не навязывает единый паттерн перерисовки. Словари — только данные в config.locale.languages; логика выбора уже в ядре.