plinkit 1.0.0-dev.0 → 1.0.0-dev.2

package/README.md

@@ -58,12 +58,79 @@ game.spawnBall()
 - `resize()` — перечитать ширину родителя и пересчитать viewport.
 - `destroy()` — остановить цикл и освободить ресурсы.
 - `getState()` — получить `{ balance, ballCost }`.
+- `setBallCost(value)` — изменить цену шарика на лету. Обновляет `getState().ballCost`
+  и синхронно вызывает `onBalanceChange`, чтобы UI мог пересчитать disabled-состояние
+  кнопки. Уже летящие шарики сохраняют свой исходный `wager` — payout считается по
+  той цене, по которой шарик был запущен. Бросает `TypeError`, если передано не
+  конечное число или отрицательное значение.
+- `setMuted(value)` — включить/выключить звук. No-op, если `options.audio` не задан.
+- `isMuted()` — текущее состояние mute. Возвращает `true`, если аудио не сконфигурировано.
+- `setVolume(value)` — общая громкость 0..1. No-op, если `options.audio` не задан.
+- `playUiTap()` — проиграть UI-сэмпл из `options.audio.uiTapUrl`. Удобно вызывать
+  из click/pointerup-обработчиков кнопок продукта, чтобы UI-звуки разделяли
+  mute/volume/auto-unlock с физикой.
+
+### Звуки
+
+Опциональный встроенный аудио-движок на Web Audio API. По умолчанию звук
+**включён** (`muted: false`); UX-toggle делается через `setMuted(value)` и
+`isMuted()`.
+
+```ts
+const game = new Plinkit({
+  // ...остальные опции
+  audio: {
+    pegHitUrl: "/sounds/peg.mp3",       // удар шарика о peg/guide
+    bucketHitUrl: "/sounds/bucket.mp3", // попадание в корзину (момент settle)
+    uiTapUrl: "/sounds/tap.mp3",        // UI-клик, проигрывается через playUiTap()
+    masterVolume: 0.6,
+  },
+})
+
+spawnButton.addEventListener("click", () => {
+  game.playUiTap()
+  game.spawnBall()
+})
+
+soundToggle.addEventListener("click", () => {
+  game.setMuted(!game.isMuted())
+})
+```
+
+`pegHitUrl` срабатывает на каждом столкновении с пегом — громкость линейно
+зависит от скорости столкновения, плюс throttling per-ball ≤1 звук в 35 мс.
+`bucketHitUrl` играется один раз при попадании шарика в корзину (без throttling
+и с фиксированной громкостью) — это сигнал «раунд завершён». `uiTapUrl` —
+короткий сэмпл UI-клика; его проигрывает `playUiTap()`, который продукт
+вызывает из своих click/pointerup-обработчиков. Все три звука разделяют общий
+`masterVolume` и состояние mute.
+
+Под капотом:
+
+- **Авто-разблокировка на мобильных.** `PlinkitAudio` ставит глобальные слушатели
+  `pointerdown` / `pointerup` / `touchstart` / `touchend` / `keydown` на `window`
+  с `capture: true`. На первом же жесте `AudioContext.resume()` снимает
+  suspended-state; слушатели сразу же снимаются. Дополнительно играется
+  silent-buffer ping (`(1, 1, sampleRate)` с gain `0.00001`), чтобы окончательно
+  «разбудить» iOS Web Audio — без этого первый реальный звук на iOS Safari
+  иногда не воспроизводится.
+- **`visibilitychange`.** При возврате вкладки в видимое состояние контекст
+  повторно резюмится — iOS/Safari часто оставляет его `interrupted` после фона.
+- **Анти-«пулемёт».** Лимит одновременных голосов (16) и лёгкая вариация
+  `playbackRate` (`±8%`) — чтобы частые peg-удары не сливались в монотонный шум.
+- **До первого жеста** `playHit` тихо игнорируется. Это нормальное поведение
+  любой Web Audio игры на iOS.
 
 ### Экономика
 
 - Значения передаются через `initialBalance`, `ballCost`, `multipliers`.
 - При попадании в корзину начисляется `ballCost * multiplier`.
 - Количество корзин = `multipliers.length` = `bottomPegCount - 1`.
+- `multipliers` — это RTP-таблица и не должны меняться вместе с `ballCost`:
+  ставку масштабируйте через `setBallCost`, а множители оставляйте фиксированными.
+- Для предсказуемого UX на лендинге держите одну ставку в пределах ~5% от банка
+  (`initialBalance`). Иначе один шарик с пиковым множителем (например `×7`) может
+  дать выплату, сравнимую со всем стартовым балансом.
 
 ### houseEdge