feat: setup project

2026-09-05 15:27:53 +05:00
parent ae2a7e1ce9
commit c79681dc59
43 changed files with 2194 additions and 14 deletions
@@ -132,9 +132,10 @@ XP-кривая Melvor-подобная, уровни открывают нод

 - **M0 — каркас.** Монорепа, overlay+web скелеты, WS-эхо.
  ✅ аватар-заглушка виден в OBS
- **M1 — вертикальный срез.** `!рубить`/`!стоп`, спавн аватара (аватарка из тегов чата),
-  ходьба к дереву, брёвна + XP + уровень, автосейв, WS-снапшот+дельты,
-  камера-окно + простейший автотур.
+- **M1 — вертикальный срез.** `!рубить`/`!стоп`, спавн аватара (спрайт-человечек, ник
+  над головой в цвете чата), ходьба к дереву, брёвна + XP + уровень, автосейв,
+  WS-снапшот+дельты, камера-окно + простейший автотур, FakeTwitchSource — отладка
+  команд без живого чата.
  ✅ зритель пишет `!рубить` и видит себя рубящим в лесу
 - **M2 — руда и кузница.** `!копать` + `!ковать` + тиры топоров/кирок.
  ✅ скрафтил железный топор → рубишь заметно быстрее
@@ -152,29 +153,36 @@ XP-кривая Melvor-подобная, уровни открывают нод
  системы оборачиваем тонким интерфейсом для дешёвого fallback
 - **OBS browser source кэширует**: dev через отдельный порт, версионирование протокола
  в рукопожатии клиента/сервера
- **Аватарки Twitch CDN**: ленивая загрузка + фолбэк-спрайт
+- **Free-версии паков (Sprout Lands, Mystic Woods) — только некоммерческое**:
+  для монетизированного канала — CC0 или платная лицензия
 - **Rate limits чата**: бот отвечает дозированно
 - **EventSub**: нужен Twitch-апп (client id/secret) у стримера; EventSub WebSocket
  работает локально без публичного webhook-URL — ок для локального MVP

 ## Ассеты

-Аватар зрителя = фото профиля Twitch в кольце; спрайтовые человечки — «тела» под ними
-и фолбэк. Поэтому берём паки, где тело и голова разделены.
+Аватар зрителя = обычный спрайт-человечек целиком — лицо и тело из пака, фото профиля
+Twitch не используем. На старте все зрители с одним и тем же спрайтом; личность читается
+по нику над головой в цвете ника чата. Разные скины — на будущее (донатеры/сабы), поэтому
+пак желателен с запасом: генератор персонажей или палитрные свопы.

 ### Человечки + скины

- **LimeZu — Modern Interiors / Modern Exteriors** (itch.io, ~$10–15) — основной кандидат:
-  генератор персонажей с сотнями скинов/одежды, домики, мебель, здания уровня «ратуша»,
-  всё в одном стиле
+- **LimeZu — Modern Interiors / Modern Exteriors** (itch.io, name-your-own-price ≈ $5,
+  лицензия CC-BY: коммерция ок с указанием авторства) — основной кандидат: домики, мебель,
+  здания уровня «ратуша», предметы — всё в одном стиле; генератор персонажей в платной
+  версии пригодится, когда дойдёт до скинов донатеров
 - **Universal LPC Spritesheet Generator** (бесплатно, онлайн) — сборка спрайт-листов
  с ходьбой/анимациями из тысяч деталей. Лицензия GPL/CC-BY-SA — проверить перед коммерциализацией
- **Kenney.nl** — CC0, человечки простые геометрические — для прототипа M0–M1
+- **Kenney.nl** — CC0 (тайлы, предметы, простые человечки) — **текущая база проекта**;
+  конкретные паки подбираем при M1 (нужны: персонаж с ходьбой, деревья/камни, вода)

 ### Домики, костёр, ратуша

- **Sprout Lands** (Cup Nooble, itch.io) — милый фермерский стиль
- **Mystic Woods** (Game Endeavor, itch.io) — есть бесплатная lite-версия: домики, костёр, природа
+- **Sprout Lands** (Cup Nooble, itch.io) — милый фермерский стиль; free-версия только
+  для некоммерческого, premium от ~$4 снимает ограничение
+- **Mystic Woods** (Game Endeavor, itch.io) — есть бесплатная lite-версия: домики, костёр,
+  природа; free-версия тоже только для некоммерческого
 - **OpenGameArt.org** — много RPG-паков зданий, лицензии смешанные — читать каждую
 - **CraftPix freebies** — бесплатные наборы зданий/персонажей

@@ -184,11 +192,14 @@ XP-кривая Melvor-подобная, уровни открывают нод
   CC-BY только с готовностью указать авторство (можно в дашборде)
 2. Один стиль важнее качества каждого пака — брать линейку у одного автора
   (LimeZu закрывает людей, дома, ратушу и предметы)
-3. Прототип M0–M1 — на CC0/Kenney, красивые паки подключаем с M2+
+3. **Решено: идём полностью на бесплатном.** База — Kenney (CC0); OpenGameArt — с проверкой
+   лицензии каждого ассета. Платные паки (LimeZu ≈ $5) — опция на потом, если захочется
+   единого стиля

 ## Идеи на потом

- FakeTwitchSource: генератор фейковых зрителей/команд для разработки без живого стрима
+- Скины для донатеров/сабов: разные внешности аватаров (генератор персонажей LimeZu
+  или палитрные свопы)
 - Событие усталости: аватар временно перестаёт работать, зритель реагирует
 - Совместная работа: несколько аватаров у одной ноды дают небольшой бонус (социальная связка)
 - Рандомные события для удержания: золотая жила, дух леса и т.п.
@@ -0,0 +1,49 @@
+# Twitch: чек-лист подключения (нужен к M1)
+
+Бот-аккаунт уже есть. Осталось зарегистрировать приложение и получить токены —
+примерно 10 минут действий, делается один раз.
+
+## 1. Приложение (один раз)
+
+1. На аккаунте, который регистрирует приложение (можно сам бот-аккаунт), включите
+   2FA: twitch.tv → Настройки → Безопасность и конфиденциальность. Без 2FA
+   Twitch не даёт создавать приложения.
+2. Зайти на https://dev.twitch.tv/console под этим аккаунтом → **Register Your Application**:
+   - Name: любое уникальное, например `idle-xboct-bot`
+   - OAuth Redirect URLs: `http://localhost:3000/oauth/callback`
+   - Category: **Chat Bot**
+3. Скопировать **Client ID**, затем Manage → **New Secret** → **Client Secret**
+   (показывается один раз).
+
+## 2. Токен бота — чтение и ответы в чате (M1)
+
+Scope: `chat:read chat:edit`.
+
+- Быстрый способ: https://twitchtokengenerator.com → «Chat Bot / Quick Token» →
+  залогиниться **именно бот-аккаунтом** → получить access token и refresh token.
+- Надёжный способ (когда дойдём до M1): мини-OAuth-скрипт на redirect из п.1.
+
+## 3. Токен стримера — Channel Points (нужен только к M5, спотлайт)
+
+Scope: `channel:read:redemptions`. Получается так же (twitchtokengenerator или свой
+OAuth), но залогиниться нужно **аккаунтом стримера**. EventSub-события выкупа наград
+принимают только пользовательский токен владельца канала — токена бота тут недостаточно.
+
+## 4. Куда положить
+
+Файл `.env` в корне `packages/server/` (в git не попадает — уже в .gitignore):
+
+```env
+TWITCH_CLIENT_ID=...
+TWITCH_CLIENT_SECRET=...
+TWITCH_CHANNEL=имя_канала
+
+TWITCH_BOT_TOKEN=...
+TWITCH_BOT_REFRESH=...
+
+TWITCH_STREAMER_TOKEN=...
+TWITCH_STREAMER_REFRESH=...
+```
+
+Refresh-токены обновляет `RefreshingAuthProvider` из twurple автоматически —
+перелогиниваться вручную не придётся.