plinkit 1.0.0-dev.4 → 1.0.0

package/README.md

@@ -1,20 +1,20 @@
 # plinkit
 
-Минимальная WebGL-библиотека для игры в стиле Plinko.
+A minimal WebGL library for Plinko-style games.
 
-## Установка
+## Installation
 
 ```bash
 npm install plinkit
 ```
 
-## Быстрый старт
+## Quick Start
 
 ```ts
-import { Plinkit } from "plinkit"
+import { Plinkit } from 'plinkit'
 
-const canvas = document.querySelector("canvas")
-if (!canvas) throw new Error("Canvas not found")
+const canvas = document.querySelector('canvas')
+if (!canvas) throw new Error('Canvas not found')
 
 const game = new Plinkit({
   canvas,
@@ -53,117 +53,95 @@ game.spawnBall()
 
 ## API
 
-- `new Plinkit(options)` — создание инстанса игры.
-- `spawnBall()` — добавить новый шарик, возвращает `SpawnResult`.
-- `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()`.
+- `new Plinkit(options)` — creates a game instance.
+- `spawnBall()` — adds a new ball and returns a `SpawnResult`.
+- `resize()` — reads the parent width again and recalculates the viewport.
+- `destroy()` — stops the loop and releases resources.
+- `getState()` — returns `{ balance, ballCost }`.
+- `setBallCost(value)` — changes the ball cost at runtime. Updates `getState().ballCost`
+  and synchronously calls `onBalanceChange`, so the UI can recalculate the button's
+  disabled state. Balls that are already in flight keep their original `wager`: payout
+  is calculated from the cost the ball was launched with. Throws `TypeError` if the
+  value is not a finite number or is negative.
+- `onCollision(collision, state)` in `options` — a ball collision event for `peg`/`guide`.
+  Use it to integrate app-side external audio.
+
+### External Audio Integration
+
+Use any audio library, or wire up your own Web Audio/HTMLAudio layer in the host application.
 
 ```ts
+interface SoundPlayer {
+  play(): void | Promise<void>
+  setVolume?(value: number): void
+}
+
+const pegHit: SoundPlayer = createSoundPlayer("/sounds/peg.mp3")
+const bucketHit: SoundPlayer = createSoundPlayer("/sounds/bucket.mp3")
+const uiTap: SoundPlayer = createSoundPlayer("/sounds/ui-tap.mp3")
+
+// Optional: one-time audio initialization/unlock on the first user gesture
+prepareAudioOnFirstGesture()
+
 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,
+  // ...other options
+  onCollision: ({ speed }) => {
+    const hitVolume = Math.max(0.08, Math.min(0.45, speed / 12))
+    pegHit.setVolume?.(hitVolume)
+    pegHit.play()
   },
+  onBallSettled: () => bucketHit.play(),
 })
 
 spawnButton.addEventListener("click", () => {
-  game.playUiTap()
+  uiTap.play()
   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`) может
-  дать выплату, сравнимую со всем стартовым балансом.
+### Economy
+
+- Values are passed through `initialBalance`, `ballCost`, and `multipliers`.
+- When a ball lands in a bucket, it awards `ballCost * multiplier`.
+- The number of buckets = `multipliers.length` = `bottomPegCount - 1`.
+- `multipliers` is the RTP table and should not be changed together with `ballCost`:
+  scale the wager through `setBallCost`, and keep the multipliers fixed.
+- For predictable landing-page UX, keep a single wager within roughly 5% of the balance
+  (`initialBalance`). Otherwise, one ball with a peak multiplier (for example, `×7`) can
+  pay out an amount comparable to the entire starting balance.
 
 ### houseEdge
 
-Параметр `houseEdge` (0..1) управляет вероятностью попадания в крайние корзины:
+The `houseEdge` parameter (0..1) controls the probability of landing in edge buckets:
 
-| houseEdge | Эффект                     | RTP*   |
-|-----------|----------------------------|--------|
-| 0         | Натуральная физика         | ~120%  |
-| 0.5       | Баланс стабилен            | ~97%   |
-| 1.0       | Баланс тает                | ~73%   |
+| houseEdge | Effect           | RTP*  |
+|-----------|------------------|-------|
+| 0         | Natural physics  | ~120% |
+| 0.5       | Stable balance   | ~97%  |
+| 1.0       | Balance declines | ~73%  |
 
-*RTP (Return to Player) зависит от множителей. Значения указаны для `[7, 1.5, 0.5, 0.2, 0.1, 0, 0.1, 0.2, 0.5, 1.5, 7]`.
+*RTP (Return to Player) depends on the multipliers. Values are shown for `[7, 1.5, 0.5, 0.2, 0.1, 0, 0.1, 0.2, 0.5, 1.5, 7]`.
 
-Внутри `houseEdge` управляет тремя механизмами: центростремительная микро-сила,
-коррекция скорости при отскоке от пега и Gaussian-распределение точки спавна.
+Internally, `houseEdge` controls three mechanisms: a centripetal micro-force,
+velocity correction on peg bounce, and a Gaussian distribution for the spawn point.
 
-> **Важно:** множители откалиброваны под конкретную геометрию поля (`topPegCount`,
-> `bottomPegCount`, `radius`, `verticalStepRatio`, `sidePaddingPx`). Изменение любого
-> из этих параметров сдвигает распределение шаров и требует повторной калибровки
-> множителей. Для калибровки используйте `scripts/bench-distribution.mjs`.
+> **Important:** multipliers are calibrated for a specific board geometry (`topPegCount`,
+> `bottomPegCount`, `radius`, `verticalStepRatio`, `sidePaddingPx`). Changing any of
+> these parameters shifts the ball distribution and requires recalibrating the
+> multipliers. Use `scripts/bench-distribution.mjs` for calibration.
 
-## Разработка
+## Development
 
 ```bash
-npm run dev       # dev-сервер с демо-страницей
+npm run dev       # dev server with a demo page
 npm run verify    # lint + typecheck + smoke test
 ```
 
-### Калибровка множителей
+### Multiplier Calibration
 
 ```bash
 npx vite-node scripts/bench-distribution.mjs
 ```
 
-Скрипт прогоняет 3000 шаров на каждом значении `houseEdge` и выводит RTP.
-Подстройте множители в скрипте так, чтобы RTP ≈ 100% при `houseEdge: 0.5`.
+The script runs 3000 balls for each `houseEdge` value and prints RTP.
+Adjust the multipliers in the script so RTP is approximately 100% at `houseEdge: 0.5`.