@hezzlgames/sdk 1.1.0

package/README.md

@@ -0,0 +1,415 @@
+# Hezzl Games SDK
+
+Библиотека, через которую игра разговаривает с игровым центром. Один
+файл без зависимостей, ES5, около 20 КБ. Распространяется пакетом
+`@hezzlgames/sdk`; исходник живёт в `play.hezzl.com/sdk`.
+
+Полные требования к играм — `docs/GAME-REQUIREMENTS.md`. Здесь только
+то, как ими пользоваться; ссылки на разделы ведут туда.
+
+    hezzl-sdk.js       библиотека — кладётся в папку игры
+    index.mjs, .cjs    та же библиотека для import / require
+    index.d.ts         типы
+    bin/hezzl-sdk.mjs  команды: стенд, проверка манифеста, копирование
+    demo/game.html     пример игры на ней, с hezzl.json и economy.json
+    demo/centre.html   стенд: поддельный центр для проверки
+
+## Установка
+
+```bash
+npm i @hezzlgames/sdk
+```
+
+Три способа подключить — один и тот же файл:
+
+```html
+<!-- без сборки: файл лежит в папке игры -->
+<script src="hezzl-sdk.js"></script>
+```
+
+```bash
+npx hezzl-sdk copy .          # положить hezzl-sdk.js в папку игры
+```
+
+```js
+// со сборкой: Vite, Webpack, esbuild
+import { Hezzl } from '@hezzlgames/sdk';
+```
+
+Второй и третий способ — тот же `hezzl-sdk.js`: пакет только доставляет
+его, а игра по-прежнему обязана работать по прямой ссылке и без сети
+(раздел 10). **С нашего домена и с CDN его не подключают.** Обновление
+SDK приезжает вместе с новой сборкой игры: подняли версию пакета —
+пересобрали — сдали.
+
+**Версии.** Версия пакета (`Hezzl.version`, semver) растёт на каждый
+выпуск и уходит в `ready` полем `sdkVersion` — по нему видно, какие
+игры собраны на чём. Номер протокола (`Hezzl.sdk`, сейчас 1) — другое
+число: он меняется только когда меняется смысл существующего поля (3.8).
+
+### Команды
+
+```bash
+npx hezzl-sdk stand [port]    # поддельный центр на localhost, по умолчанию 8791
+npx hezzl-sdk check [dir]     # проверить hezzl.json и economy.json
+npx hezzl-sdk copy  [dir]     # положить hezzl-sdk.js в папку игры
+```
+
+`check` — то, что мы смотрим первым на приёмке (41.1, 41.2): реестр
+режимов, имена умений, обязательные поля, лестница цен и норма
+сундуков из 37.5. Гоняйте его перед сдачей; он же стоит в `prepack`
+пакета.
+
+### `economy.json`
+
+Для игры без сервера, которая тратит валюту центра (`currency: true`
+в манифесте). Все цены на экране — отсюда и ниоткуда больше (37.5):
+
+```json
+{
+  "boosters": { "hint": 10, "hammer": 40, "rocket": 40 },
+  "continue": [50, 100, 1500],
+  "levels": 60,
+  "chests": [
+    { "stars": 15, "boosters": [
+      { "key": "hammer", "count": 1, "chance": 0.5 },
+      { "key": "rocket", "count": 1, "chance": 0.5 }
+    ] }
+  ]
+}
+```
+
+| поле | правило |
+|---|---|
+| `boosters` | ключ — строчные латиница, цифры, подчёркивание; тот же ключ идёт в `item` просьбы `spend`. Цена — целое больше нуля |
+| `continue` | лестница цен продолжения уровня, не убывает; последняя ступень — предел (37.5) |
+| `chests` | сундуки на карте: за сколько звёзд и что может выпасть. Не больше двух бустеров, не больше одного каждого вида, `chance` — доля, которую видит человек (37.1) |
+| `levels` | длина карты, для оценки нормы бесплатных бустеров; без поля — 60 |
+
+## Зачем он
+
+Половину требований первой части он выполняет за вас:
+
+* разбирает `lang`, `theme`, `accent`, `muted`, `haptics`, `ref` из адреса
+  и проверяет их формат;
+* проверяет источник входящих сообщений — обе проверки из 3.2, включая
+  ту, про которую забывают и отключают защиту при прямом заходе;
+* держит рукопожатие: узнаёт, есть ли центр рядом и что он умеет;
+* складывает команды, пришедшие раньше готовности, и не теряет их;
+* держит хранилище: через центр, а без центра — своё, с префиксом;
+* соблюдает частоту сообщений и пропускает финальный счёт мимо неё;
+* ведёт разговор о валюте центра: баланс, товары, покупка, списание,
+  кошелёк — с типизированными отказами и без своих окон;
+* собирает `window.HezzlGame` с правильными именами методов.
+
+**Файл кладётся в папку игры и подключается оттуда.** С нашего домена
+его не подключают: игра обязана работать по прямой ссылке и без сети,
+а обращения на сторонние домены запрещены (раздел 10). Обновление SDK
+приезжает вместе с новой сборкой игры.
+
+## Как подключить
+
+```html
+<script src="hezzl-sdk.js"></script>
+<script src="game.js"></script>
+```
+
+## Минимальная игра
+
+```js
+Hezzl.init({
+  id: 'my-game',            // ярлык из каталога, как в hezzl.json
+  version: '1.0.0',
+  modes: ['quick'],         // ключи из реестра 20.1
+  orientation: 'any',
+  on: {
+    mute:   function (muted) { sound.enabled = !muted; },
+    pause:  function () { engine.pause(); },
+    resume: function () { engine.resume(); }
+  }
+});
+
+Hezzl.ready();              // когда игра действительно принимает ввод
+```
+
+**`supports` выводится из обработчиков**, объявлять его отдельно не надо.
+Объявить умение и не реализовать его по построению невозможно — а это
+самое частое расхождение между манифестом и поведением.
+
+### `ready` — обязателен, и это не формальность
+
+Зовётся, когда игра принимает ввод, а не когда загрузился скрипт: по нему
+центр отпускает заставку.
+
+**Подключив библиотеку, вы делаете `ready` обязательным на практике.**
+SDK объявляет игру на `window`, центр видит объявление и начинает ждать
+её слова. Игра без `ready` держит заставку **20 секунд**, а потом человек
+получает экран «Игра долго не отвечает». Без библиотеки та же игра просто
+открылась бы — центр снял бы заставку по загрузке кадра.
+
+Раньше `ready` не позвать было незаметно. Теперь — заметно, и заметно
+человеку, а не вам.
+
+Заставку `ready` при этом **не сокращает**: у неё своя минимальная
+длительность и своя сцена, а `ready` только отпускает её. Позвать его
+рано, «чтобы быстрее», смысла не имеет — раньше минимума заставка
+не уйдёт. Позвать поздно — человек лишнее время смотрит на лоадер.
+
+Правильный момент — первый кадр, на котором касание уже что-то делает.
+
+## Настройки при запуске
+
+```js
+Hezzl.settings   // { lang, theme, accent, muted, haptics, ref }
+```
+
+Пустая строка означает «решай сама»: человек оставил настройку
+на «Системе». Порядок разрешения — адрес, своя сохранённая, браузер:
+
+```js
+var lang = Hezzl.resolve('lang', saved.lang, function () {
+  return (navigator.language || 'ru').slice(0, 2) === 'en' ? 'en' : 'ru';
+});
+```
+
+Настройка из адреса не запоминается как выбор человека (раздел 2).
+
+## Хранилище
+
+```js
+Hezzl.storage.get('progress').then(function (data) { ... });
+Hezzl.storage.set('progress', data, { sync: true, schema: 3 });
+Hezzl.storage.remove('draft');
+Hezzl.storage.keys();
+```
+
+Префикс не пишется — его ставит SDK. Вызовы до рукопожатия копятся
+и разрешаются, как только известен режим: ждать `ready`, чтобы прочитать
+прогресс, не нужно.
+
+**`sync`** — уносить ли на сервер, когда человек войдёт. Прогресс
+и состояние обучения — да. Громкость, скин, уровень качества — нет.
+
+**Отказ типизирован**, ветвиться надо по `reason`, а не по тексту:
+
+```js
+Hezzl.storage.set('progress', data, { sync: true }).catch(function (e) {
+  if (e.reason === 'quota') dropCaches();       // освободить необязательное
+  else if (e.reason === 'unavailable') sayOnce('Прогресс не сохранится');
+});
+```
+
+Значения: `unavailable`, `quota`, `invalid`, `unknown` (раздел 7.6).
+
+## События
+
+```js
+Hezzl.gameStart({ mode: 'levels', level: 3 });
+Hezzl.score(1200, { best: 4000 });
+Hezzl.milestone('combo', 5);          // what — из реестра 3.4
+Hezzl.levelComplete({ level: 3, stars: 2 });
+Hezzl.levelFailed({ level: 3 });
+Hezzl.gameOver({ score: 1200, best: 4000 });
+```
+
+`score` можно звать на каждое очко: SDK сам придержит лишнее и отправит
+последнее значение хвостом. Перед `gameOver` финальный счёт уходит
+всегда, мимо ограничения, — иначе центр покажет предпоследний результат.
+
+## Просьбы к центру
+
+```js
+Hezzl.share({ text: 'Собрал 2048 за 214 ходов' });
+Hezzl.support({ message: '...', state: { level: 12 } });
+Hezzl.exit();
+Hezzl.signin();
+
+Hezzl.auth().then(function (a) { ... });                    // a.signedIn, a.code
+Hezzl.profile(['name', 'avatar']).then(function (a) { ... }); // a.profile
+```
+
+**Показывать эти кнопки можно только после рукопожатия и только те,
+что центр умеет:**
+
+```js
+if (Hezzl.can('share')) showShareButton();
+```
+
+**`signin()` ничего не возвращает** — это просьба, а не вопрос. Центр
+поднимает свой экран входа поверх игры; игра под ним продолжает жить,
+и человек может закрыть его крестиком и играть дальше. Ответ придёт
+отдельно и не сразу: `signedin` — когда человек вошёл, `signincancelled` —
+когда закрыл экран, так и не войдя. Ждать в цепочке нельзя: разговор
+занимает минуту, а бывает, что не заканчивается вовсе.
+
+```js
+Hezzl.init({ on: {
+  signedin:         function (id) { unlockTournament(id); },
+  signincancelled:  function () { showLocalOnlyNotice(); }
+} });
+```
+
+Отказ приходит только тому, кто вход просил. Человек, открывший вход
+своей кнопкой в шапке центра, игре ничего не обещал, и та об этом
+не узнаёт.
+
+**`auth().code` появится вместе с серверной частью.** Сейчас центр
+отвечает только `signedIn`: кода обмена он не выдумывает, потому что
+игра пошла бы менять его на сеанс и получила бы отказ. Ветвитесь
+по `signedIn`, а `code` проверяйте на существование.
+
+`Hezzl.mode()` возвращает `unknown`, `centre` или `standalone`. Пока
+`unknown` — рукопожатие идёт, зависимые элементы не показываются.
+При прямом заходе режим известен сразу.
+
+## Валюта центра
+
+У центра одна твёрдая валюта на все игры. Человек получает её
+за задания и покупает за деньги — в центре, не в игре. Игра её только
+тратит: на товары из нашего каталога или на своё, по своей цене.
+Полные правила — раздел 7.9 требований; здесь — как этим пользоваться.
+
+```js
+if (Hezzl.can('balance')) showShop();   // у центра без валюты магазина нет
+
+Hezzl.currency();                        // { key, title, icon, amount } или null
+Hezzl.balance().then(function (a) { hud(a.amount); });   // a.signedIn, a.amount
+```
+
+`currency()` синхронный: значок и название приходят с рукопожатием,
+сумма — с первым же ответом, где она есть. Рисовать счётчик можно
+сразу после `ack`, не дожидаясь `balance()`.
+
+### Кейс 1 — товар из нашего каталога
+
+Товар заведён у нас: цена в валюте центра, награда в ресурсах игры.
+Игра не хранит ни того ни другого — берёт из `goods()`:
+
+```js
+Hezzl.goods().then(function (a) { renderShop(a.goods); });
+// a.goods: [{ id, title, picture, price, award }]
+
+Hezzl.buy(good.id).then(function (done) {
+  give(done.award);                      // выдаём то, что ответил центр
+  hud(done.amount);                      // сколько осталось
+}, function (e) {
+  if (e.reason === 'insufficient') say('Не хватает ' + e.need);
+  else if (e.reason !== 'cancelled') say('Не получилось');
+});
+```
+
+Между вызовом и ответом центр делает две вещи сам, и игре о них
+знать не нужно: **спрашивает подтверждение** своим окном поверх
+кадра и, если валюты не хватает, **показывает кошелёк** — где взять.
+На это время игра получает `pause`, по закрытии — `resume`.
+Обещание висит столько, сколько человек думает: срока у него нет,
+пока центр держит разговор.
+
+`Hezzl.buy(id, { wallet: false })` — не показывать кошелёк, а сразу
+отказать `insufficient`. Нужно редко: когда игра сама хочет сказать
+про нехватку и открыть кошелёк позже, `wallet()`.
+
+### Кейс 2 — товар свой, цена своя
+
+Игра без сервера: бустеры, подсказки, продолжение партии. Цену
+назначает игра, центр только списывает — с тем же подтверждением
+и тем же кошельком при нехватке:
+
+```js
+Hezzl.spend(10, { item: 'Подсказка' }).then(function (done) {
+  bag.hints++;                           // выдаём после ok, не по нажатию
+  hud(done.amount);
+}, refuse);
+```
+
+`item` — что куплено, до 80 знаков: его человек видит в окне
+подтверждения, а мы — в отчёте.
+
+### Кошелёк и уведомления
+
+```js
+Hezzl.wallet({ reason: 'Магазин' }).then(function (w) { hud(w.amount); });  // w.bought
+
+Hezzl.init({ on: {
+  balance:      function (amount) { hud(amount); },     // изменился — по любой причине
+  walletclosed: function (amount, d) { /* d.bought */ }
+} });
+```
+
+`balance` приходит без просьбы: награда за задание, покупка в кошельке,
+покупка в другой вкладке. Опрашивать баланс по таймеру не нужно.
+
+### Отказы
+
+Ветвиться по `reason`; текст — технический и не для показа:
+
+| `reason` | что случилось | что делать |
+|---|---|---|
+| `insufficient` | не хватило, и кошелёк закрыли, не пополнив; `need` — сколько | сказать число, оставить кнопку |
+| `cancelled` | человек нажал «отмена» в подтверждении | ничего: он сам передумал |
+| `signin` | человека нет, а вход он закрыл | «войдите, чтобы покупать» |
+| `notfound`, `disabled` | товара нет или он выключен у нас | убрать из витрины, обновить `goods()` |
+| `unavailable` | центра нет или у него нет валюты | магазина не показывать вовсе |
+| `invalid` | плохие доводы: не целое, не больше нуля | ошибка сборки |
+| `unknown` | сервер не ответил или отказал | «попробуйте ещё раз», ничего не выдавать |
+
+**Ничего не выдаётся до `ok`.** Списание подтверждает и проводит
+центр; игра, выдавшая товар по нажатию, отдаёт его бесплатно
+при любом отказе.
+
+## Отказы
+
+```js
+Hezzl.error('asset_load', 'sprites.png не загрузился', false);
+```
+
+Коды — из своего набора: `asset_load`, `storage_write`, `webgl_lost`,
+`runtime` (раздел 38). `message` техническая, для нас, без личных данных.
+
+## Стенд
+
+`demo/centre.html` — поддельный центр. Он говорит по тому же протоколу
+и показывает каждое сообщение в обе стороны.
+
+```bash
+npx hezzl-sdk stand
+# затем открыть http://localhost:8791/demo/centre.html
+# из репозитория: node tools/serve.mjs 8791 sdk
+```
+
+Что стоит проверить на нём до сдачи:
+
+| проверка | как | что должно быть |
+|---|---|---|
+| рукопожатие | открыть игру | `ready` от игры, `ack` в ответ |
+| умения | посмотреть `ready` | `supports` совпадает с `hezzl.json` |
+| настройки | выставить язык, тему, цвет, метку | применились при запуске |
+| команды | нажать кнопки команд | игра отреагировала на каждую |
+| частота | быстро набрать очки | `score` не чаще раза в секунду |
+| финальный счёт | закончить партию | последний `score` совпал с показанным |
+| хранилище | сыграть, перезапустить | прогресс на месте |
+| отказ по квоте | галка «хранилище переполнено» | игра сказала, а не промолчала |
+| **центр молчит** | снять галку «отвечать на `ready`» | режим `standalone`, кнопки центра скрыты |
+| **`ready` не позван** | закомментировать `Hezzl.ready()` | заставка висит 20 с и сменяется отказом — так это увидит человек |
+| прямой заход | открыть `demo/game.html` без стенда | игра работает, прогресс в своём хранилище |
+| покупка | нажать цену товара | окно центра поверх игры, `pause`; после «списать» — награда и `resume` |
+| нехватка | цена выше баланса | кошелёк с точной нехваткой; пополнить — покупка продолжится, закрыть — `insufficient` с числом |
+| отмена | «отмена» в подтверждении | игра молчит, ничего не выдано |
+| **без валюты** | снять галку «центр умеет валюту» | магазина и кнопок за валюту нет вовсе |
+| сбой сервера | галка «сервер Balance отказывает» | `unknown`, баланс не тронут, товар не выдан |
+
+Три строки, выделенные жирным, — самые полезные. Игра, которая ломается
+без центра или молчит вместо `ready`, доезжает до приёмки чаще остальных,
+а стоит проверки в одну минуту.
+
+## Чего SDK не делает
+
+* не решает, какой язык показать: порядок ваш, `resolve` только
+  подсказывает;
+* не рисует интерфейс — ни кнопок, ни окон; окно подтверждения
+  и кошелёк — тоже не его, а центра;
+* не хранит цены и состав товаров: они у нас, приходят в `goods()`;
+* не проверяет манифест: совпадение `hezzl.json` и `ready` смотрим
+  на приёмке;
+* не пишет в консоль. Отладочный вывод включается `debug: true`
+  в `init` и в собранной игре остаться не должен (раздел 38).

package/bin/hezzl-sdk.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * hezzl-sdk — команды пакета @hezzlgames/sdk.
+ *
+ *   hezzl-sdk stand [port]      поддельный игровой центр на localhost
+ *   hezzl-sdk check [dir]       проверить hezzl.json и economy.json игры
+ *   hezzl-sdk copy  [dir]       положить hezzl-sdk.js в папку игры
+ *
+ * Без зависимостей: подрядчику достаточно node 18.
+ */
+import { createServer } from 'node:http';
+import { readFile, stat, copyFile } from 'node:fs/promises';
+import { join, extname, normalize, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const [, , command = 'help', arg] = process.argv;
+
+const MODES = ['quick', 'levels', 'pvp_bot', 'arena', 'hotseat'];               /* реестр 20.1 */
+const COMMANDS = ['mute', 'haptics', 'pause', 'resume', 'restart',
+                  'setlang', 'settheme', 'setaccent'];                            /* таблица 3.1 */
+const ORIENTATIONS = ['portrait', 'landscape', 'any'];
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8', '.json': 'application/json; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.png': 'image/png', '.svg': 'image/svg+xml',
+  '.jpg': 'image/jpeg', '.webp': 'image/webp', '.mp3': 'audio/mpeg', '.woff2': 'font/woff2'
+};
+
+async function stand(port) {
+  port = Number(port) || 8791;
+  /* Корень — сам пакет: demo/centre.html подключает ../hezzl-sdk.js.
+     Своя игра открывается по адресу в поле стенда, например
+     http://localhost:5173/index.html — стенд её только показывает. */
+  const server = createServer(async (req, res) => {
+    const path = normalize(decodeURIComponent(req.url.split('?')[0]));
+    let file = join(PKG, path === '/' ? '/demo/centre.html' : path);
+    if (!file.startsWith(PKG)) { res.writeHead(403); res.end(); return; }
+    try {
+      if ((await stat(file)).isDirectory()) file = join(file, 'index.html');
+      const body = await readFile(file);
+      res.writeHead(200, { 'Content-Type': TYPES[extname(file)] || 'application/octet-stream', 'Cache-Control': 'no-store' });
+      res.end(body);
+    } catch { res.writeHead(404); res.end('нет такого файла'); }
+  });
+  server.listen(port, () => {
+    console.log(`стенд: http://localhost:${port}/demo/centre.html`);
+    console.log('в поле «адрес игры» — адрес вашей сборки; пример игры — game.html');
+  });
+}
+
+/* ── проверка манифеста и экономики ──────────────────────────────── */
+
+function isInt(v) { return Number.isInteger(v) && v > 0; }
+
+async function readJson(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (e) { return e.code === 'ENOENT' ? undefined : { __broken: String(e.message) }; }
+}
+
+async function check(dir) {
+  dir = resolve(dir || '.');
+  const bad = [], warn = [];
+  const manifest = await readJson(join(dir, 'hezzl.json'));
+  if (manifest === undefined) bad.push('нет hezzl.json (41.1)');
+  else if (manifest.__broken) bad.push('hezzl.json не разбирается: ' + manifest.__broken);
+  else {
+    const m = manifest;
+    if (!/^[a-z0-9-]{2,40}$/.test(m.id || '')) bad.push('id: ярлык строчными латиницей и дефисом, как в каталоге');
+    if (!/^\d+\.\d+\.\d+/.test(m.version || '')) bad.push('version: семантическая версия');
+    if (m.sdk !== 1) bad.push('sdk: сегодня протокол 1');
+    if (!Array.isArray(m.modes) || !m.modes.length) bad.push('modes: непустой список из реестра 20.1');
+    else for (const x of m.modes) if (!MODES.includes(x)) bad.push(`modes: «${x}» нет в реестре 20.1 (${MODES.join(', ')})`);
+    if (!ORIENTATIONS.includes(m.orientation)) bad.push('orientation: portrait | landscape | any');
+    if (!Array.isArray(m.supports)) bad.push('supports: список умений (3.6)');
+    else for (const x of m.supports) {
+      if (!COMMANDS.includes(x)) bad.push(`supports: «${x}» — не команда игры; storage, auth, balance — умения центра (3.1)`);
+    }
+    if (typeof m.offline !== 'boolean') bad.push('offline: true | false (раздел 11)');
+    if (!Array.isArray(m.hosts)) bad.push('hosts: список доменов, пусто — норма (раздел 10)');
+    if (m.entry && !/\.html?$/.test(m.entry)) bad.push('entry: html-файл');
+    if (!m.title || typeof m.title.ru !== 'string') bad.push('title.ru обязателен (раздел 27)');
+    if (m.currency === undefined) warn.push('currency не указан: считаем, что бустеров и продолжений в игре нет (37.5)');
+  }
+
+  const economy = await readJson(join(dir, 'economy.json'));
+  const needsEconomy = manifest && manifest.currency === true && manifest.purchases !== true;
+  if (needsEconomy && economy === undefined) bad.push('currency: true у игры без сервера требует economy.json (37.5, 41.2)');
+  if (economy && economy.__broken) bad.push('economy.json не разбирается: ' + economy.__broken);
+  else if (economy) {
+    const e = economy;
+    if (!e.boosters || typeof e.boosters !== 'object') bad.push('economy.boosters: { ключ: цена }');
+    else for (const [key, price] of Object.entries(e.boosters)) {
+      if (!/^[a-z0-9_]{1,32}$/.test(key)) bad.push(`economy.boosters: ключ «${key}» — строчные латиница, цифры, подчёркивание; тот же ключ уходит в item просьбы spend`);
+      if (!isInt(price)) bad.push(`economy.boosters.${key}: цена — целое больше нуля`);
+    }
+    if (e.continue !== undefined) {
+      if (!Array.isArray(e.continue) || !e.continue.length || !e.continue.every(isInt)) bad.push('economy.continue: лестница цен, целые больше нуля, например [50, 100, 1500]');
+      else for (let i = 1; i < e.continue.length; i++) if (e.continue[i] < e.continue[i - 1]) bad.push('economy.continue: цена не убывает с каждым продолжением (37.5)');
+    }
+    if (e.chests !== undefined) {
+      if (!Array.isArray(e.chests)) bad.push('economy.chests: список сундуков');
+      else e.chests.forEach((c, i) => {
+        const at = `economy.chests[${i}]`;
+        if (!isInt(c.stars)) bad.push(`${at}.stars: за сколько звёзд (22.2)`);
+        const drops = Array.isArray(c.boosters) ? c.boosters : [];
+        let total = 0;
+        const seen = new Set();
+        for (const d of drops) {
+          if (!d || !e.boosters || !(d.key in e.boosters)) bad.push(`${at}: бустер «${d && d.key}» не описан в economy.boosters`);
+          if (!isInt(d.count) || d.count > 1) bad.push(`${at}: не больше одного бустера каждого вида (37.5)`);
+          if (typeof d.chance !== 'number' || d.chance <= 0 || d.chance > 1) bad.push(`${at}: chance — доля от 0 до 1, шансы показываются человеку (37.1)`);
+          if (seen.has(d.key)) bad.push(`${at}: «${d.key}» дважды`);
+          seen.add(d.key);
+          total += d.count || 0;
+        }
+        if (total > 2) bad.push(`${at}: не больше двух бустеров в сундуке (37.5)`);
+      });
+      if (e.chests.length && manifest && Array.isArray(manifest.modes) && manifest.modes.includes('levels')) {
+        const levels = isInt(e.levels) ? e.levels : 60;
+        const stars = e.chests.reduce((n, c) => Math.max(n, c.stars || 0), 0);
+        const chestsOnMap = stars ? Math.floor(levels * 3 / stars) : 0;
+        const perChest = e.chests[0].boosters ? e.chests[0].boosters.reduce((n, d) => n + (d.count || 0), 0) : 0;
+        const free = chestsOnMap * perChest;
+        if (free > levels / 4) warn.push(`бесплатных бустеров до ${free} на ${levels} уровней — чаще одного на четыре уровня, это раздача (37.5)`);
+      }
+    }
+  }
+
+  for (const w of warn) console.log('  ~ ' + w);
+  for (const b of bad) console.log('  ✗ ' + b);
+  if (bad.length) { console.log(`\n${bad.length} ошибок в ${dir}`); process.exit(1); }
+  console.log(`✓ ${dir}: hezzl.json${economy ? ' и economy.json' : ''} в порядке`);
+}
+
+async function copy(dir) {
+  const to = join(resolve(dir || '.'), 'hezzl-sdk.js');
+  await copyFile(join(PKG, 'hezzl-sdk.js'), to);
+  const { version } = JSON.parse(await readFile(join(PKG, 'package.json'), 'utf8'));
+  console.log(`hezzl-sdk.js ${version} → ${to}`);
+  console.log('подключите до кода игры: <script src="hezzl-sdk.js"></script>');
+}
+
+const commands = { stand, check, copy };
+if (!commands[command]) {
+  console.log(`hezzl-sdk <команда>\n\n  stand [port]   поддельный игровой центр, по умолчанию 8791\n  check [dir]    проверить hezzl.json и economy.json\n  copy  [dir]    положить hezzl-sdk.js в папку игры`);
+  process.exit(command === 'help' ? 0 : 1);
+}
+commands[command](arg).catch((e) => { console.error(e.message); process.exit(1); });