Skip to content
JJSGxKDPublic

About

Кроссплатформенная HTML5-игра для Telegram, MAX, VK и браузера

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

6,206 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bullet-heaven / dungeon-runner мини-игра

Кроссплатформенная HTML5-игра для Telegram, MAX, VK и браузера. Приоритет разработки — Telegram первым, MAX и VK портируются после (обоснование — docs/02-roadmap.md §«Приоритет платформ»). Полная проектная документация — в docs/, начать оттуда. Этот файл — только о том, как поднять и запустить проект: сначала быстрый старт, за ним подробная инструкция с нуля для тех, кто раньше не запускал веб-проекты.

Лицензия: PolyForm Noncommercial 1.0.0 — репозиторий публичный, но коммерческое использование посторонними запрещено. Подробности и внутреннее соглашение для команды — docs/12-ip-and-licensing.md.

Быстрый старт

Для тех, у кого уже стоят Git, Node.js 22.22.3, pnpm и Docker Desktop. Если чего-то из этого нет или всё это впервые — ниже есть подробная инструкция с нуля.

git clone -b dev https://github.com/JJSGxKD/rubezh.git   # dev — текущая работа, см. «Ветки»
cd rubezh
corepack enable pnpm            # один раз на машину, из PowerShell от администратора
Copy-Item .env.example .env
pnpm install
docker compose up -d            # Postgres + Redis
pnpm --filter backend-api prisma:deploy
pnpm dev                        # бэкенд :4000 + Telegram-клиент :5173

Игра — http://localhost:5173. Без бэкенда хватит pnpm dev:telegram: Docker для этого не нужен. Аккаунт, сохранения и лидерборд в обычном браузере, без Telegram, включаются шестью строками в .env — они в шаге 11.

Остальные сборки и бэкенд по отдельности, каждая команда в своём окне:

pnpm dev:all        # бэкенд + все три клиента
pnpm dev:telegram   # apps/web-telegram, http://localhost:5173
pnpm dev:max        # apps/web-max,      http://localhost:5174
pnpm dev:vk         # apps/web-vk,       http://localhost:5175
pnpm dev:backend    # backend/api,       http://localhost:4000
pnpm dev:admin      # apps/admin,        http://127.0.0.1:5176 — панель команды
pnpm stop           # освободить порты, если процесс пережил Ctrl+C

Порты закреплены, карта — docs/20-env-and-ports.md §2. Туннель для проверки в Telegram с телефона, бот и секреты — там же, §4.

Панели нужен бэкенд со входом — заданным JWT_ACCESS_SECRET, панель работает вместе с ним. Вход — через бота: страница входа сразу показывает QR и кнопку, которые открывают бота в Telegram, и код; бот — тот же код и кнопку «Войти» (нужны чтение обновлений бота и роль в панели). На своей машине проще вход разработчика: при AUTH_DEV_LOGIN="true" форма dev-1:Имя даёт владельца. Dev-сервер панели слушает только 127.0.0.1 и без туннеля — это блокировки и начисления, телефону тестера там делать нечего.

Секреты (TELEGRAM_WEBHOOK_SECRET, EXPORT_PSEUDONYM_KEY и те, что появятся дальше) генерируются командой openssl rand -hex 32 — openssl идёт вместе с Git for Windows. У каждого секрета своё значение.

Windows: nvm-windows не читает .nvmrc — версию называют явно: nvm install 22.22.3, nvm use 22.22.3. Сам .nvmrc остаётся источником истины и используется в CI. Почему pnpm, а не npm или bun, — docs/16-tech-stack-decisions.md §2.

Ветки: dev для проверки, main — выпуски

Работа идёт в ветке dev. Каждый влитый PR попадает туда и выпускает предрелиз vX.Y.Z-rc.N — это о нём приходит сводка в чат команды. В main изменения приезжают только выпуском, одним релизным PR в конце этапа, поэтому main отстаёт от dev на всё, что влито после последнего выпуска, — бывает, на целый этап.

Ветка Что в ней Для чего
dev Всё влитое, включая то, о чём только что пришла сводка Играть, проверять и тестировать — команде и тестерам
main Последний выпуск Выкладка на сервер: она идёт из тега выпуска

Инструкции ниже сразу клонируют dev (git clone -b dev). Если вы клонировали без -b dev, вы в main. Переключиться нужно один раз:

git fetch                                  # узнать о ветке, если клонировали давно
git switch dev
pnpm install                               # в dev могут быть новые библиотеки
pnpm --filter backend-api prisma:deploy    # и новые таблицы

Дальше git pull забирает изменения уже из dev. В какой ветке вы сейчас, показывает git branch --show-current. После переключения сверьте .env с шагом 11: настройки в ветках могут различаться. Сейчас, например, в dev вход под аккаунтом, и нужных для него строк в .env, заполненном по инструкции к main, нет.

README на GitHub показывается из main и до выпуска может отставать. Инструкция к dev — в README.md у вас в папке или на GitHub в ветке dev.

Вернуться на выпуск — git switch main. Схема базы меняется по правилу «сначала добавить, убрать потом» (docs/09-ci-cd.md §4), поэтому main обычно работает и на базе, обновлённой из dev. Не стартует — позовите владельца репозитория.

Свои правки — в своей ветке от dev и PR в dev (docs/09-ci-cd.md §8).

Первый запуск с нуля (подробно)

Инструкция для тех, кто раньше не запускал веб-проекты, а работал в Unity, где открываешь проект и жмёшь Play. Шаги идут по порядку, ничего пропускать не нужно. Первый раз займёт около часа, почти всё время — установка программ.

Чем это отличается от Unity

В Unity игра собирается в файл, а здесь файла нет. Игра — это веб-страница, и показывает её маленький сервер, который вы запускаете у себя командой в терминале. Пока он работает, игра открывается в браузере по адресу http://localhost:5173 (localhost — «этот компьютер», в интернет ничего не уходит). Правите код или данные, например packages/core-game/src/content/enemies.ts, — страница обновляется сама, пересобирать ничего не нужно.

Запустить можно двумя способами:

Способ Что работает Что поставить
1. Только игра Вся игра: меню, забеги, настройки. Прогресс хранится в браузере Git, Node.js, pnpm (шаги 1–7)
2. Игра и сервер То же плюс сохранение забегов на сервере и лидерборд Всё из первого способа и Docker Desktop (шаги 8–12)

Начните с первого: его хватает, чтобы играть и править баланс. Открыть игру внутри Telegram на телефоне пока нельзя — нужен туннель в интернет, его поднимает владелец репозитория.

Шаг 0. Терминал

Все команды вводятся в PowerShell — стандартном терминале Windows.

  • Открыть: правый клик по кнопке «Пуск» → «Терминал». Появится окно с мигающим курсором.
  • Команду из блока ниже скопировать и вставить (Ctrl+V или правый клик мышью), потом Enter. Одна строка — одна команда: вставляйте по одной и ждите, пока снова появится строка вида PS C:\...>.
  • Текст после # — пояснение, терминал его пропускает.
  • Остановить то, что сейчас работает (например, сервер игры), — Ctrl+C в этом окне.
  • После установки новой программы закройте терминал и откройте заново, иначе он её не увидит.

Шаг 1. Git

Git скачивает проект и потом забирает обновления от команды.

  1. Скачать установщик с https://git-scm.com/download/win («Click here to download»).

  2. Запустить и на всех экранах жать «Next»: умолчания подходят.

  3. В новом терминале проверить:

    git --version

    Ответ — что-то вроде git version 2.51.1.windows.1.

Если привыкли к GitHub Desktop, клонировать можно и через него, но Git всё равно нужен: команды ниже его используют.

Шаг 2. Node.js

Node.js запускает сервер игры и все инструменты проекта. Нужна версия 22.22.3 или новее из линейки 22: на более старой установка остановится с ошибкой про версию.

  1. Скачать установщик: https://nodejs.org/dist/v22.22.3/node-v22.22.3-x64.msi

  2. Запустить, жать «Next». Галочку «Automatically install the necessary tools» не ставить — она ставит лишнее.

  3. В новом терминале:

    node -v

    Должно быть v22.22.3.

Шаг 3. pnpm

pnpm скачивает библиотеки, из которых собран проект, — примерно как Package Manager в Unity. Он уже лежит внутри Node.js, его нужно только включить.

  1. Открыть терминал от администратора: правый клик по «Пуск» → «Терминал (администратор)» → «Да».

  2. Выполнить:

    corepack enable pnpm

    Команда ничего не выводит — так и должно быть. Окно администратора закрыть.

  3. Открыть обычный терминал:

    pnpm -v

    Если спросит Corepack is about to download ... Do you want to continue?, ввести y и Enter. Ответ — 10.15.0.

Если вместо версии ошибка «выполнение сценариев отключено в этой системе» — см. «Если что-то пошло не так».

Шаг 4. Скачать проект

Держите проект в короткой папке без русских букв и пробелов в пути и не на рабочем столе: он часто синхронизируется с OneDrive, а тысячи мелких файлов библиотек синхронизацию душат. Хороший вариант — C:\dev.

New-Item -ItemType Directory -Force C:\dev   # создать папку, если её нет
cd C:\dev
git clone -b dev https://github.com/JJSGxKD/rubezh.git
cd rubezh

-b dev — ветка, в которой идёт работа: в ней свежая версия игры. Почему не main — в разделе «Ветки».

Если Git попросит войти в GitHub — войдите аккаунтом, которому дали доступ к репозиторию. Дальше все команды выполняются в папке C:\dev\rubezh: в начале строки терминала должно быть PS C:\dev\rubezh>. В новом терминале сначала cd C:\dev\rubezh.

Шаг 5. Файл настроек

Copy-Item .env.example .env

.env — настройки запуска вашей копии проекта. Он у каждого свой и в git не попадает, так задумано. Пока в нём ничего менять не нужно.

Шаг 6. Установить библиотеки

pnpm install

Одна–две минуты, несколько сотен библиотек. Заканчивается строкой Done in .... Жёлтые предупреждения можно не читать, а красный ERR_... в конце — ошибка, см. таблицу в конце.

Шаг 7. Запустить игру

pnpm dev:telegram

Когда в терминале появится Local: http://localhost:5173/, откройте в браузере http://localhost:5173 (удобнее Chrome или Edge).

  • Первый экран — «Закрытый технический тест», кнопка «Понятно, играем».
  • Управление на компьютере — зажать левую кнопку мыши и вести, как палец по экрану телефона. Оружие стреляет само.
  • Посмотреть, как на телефоне: F12 → Ctrl+Shift+M → вверху выбрать модель, например iPhone 12 Pro. Вернуть — снова Ctrl+Shift+M.
  • Пока играете, окно терминала не закрывайте: это и есть сервер игры. Закончили — Ctrl+C в нём.
  • Красные строки http proxy error: /api/v1/events и ECONNREFUSED в терминале — нормально для первого способа: игра пытается отправить статистику, а сервера нет.

Правите файл в packages/core-game/src/content/, сохраняете — браузер подхватывает правку сам. Как устроены враги, волны и оружие — CLAUDE.md, разделы «Как добавить...».

Инструменты команды — режим разработчика с читами, стресс-тест, витрина компонентов, звуковая лаборатория. Открыть .env в Блокноте:

notepad .env

найти строку VITE_DEV_TOOLS="" (Ctrl+F), заменить на VITE_DEV_TOOLS="1", сохранить (Ctrl+S). Сервер перезапустится сам; обновите страницу — инструменты появятся в меню ☰ → «Настройки» → «Для тестировщиков».

Первый способ готов. Дальше — только если нужны сохранения на сервере и лидерборд.

Шаг 8. Docker Desktop

Серверу игры нужны база данных (Postgres) и быстрое хранилище (Redis). Ставить их по отдельности не нужно: Docker запускает их готовыми в изолированных «коробках» — контейнерах, а Docker Desktop — программа, которая эти контейнеры держит.

  1. Скачать с https://www.docker.com/products/docker-desktop/ → «Download for Windows — AMD64» (для ARM-процессора, например Snapdragon, — ARM64).

  2. Запустить установщик, галочку «Use WSL 2 instead of Hyper-V» оставить.

  3. Перезагрузить компьютер, если попросит.

  4. Запустить Docker Desktop из «Пуска», принять соглашение. Входить в аккаунт не обязательно — «Skip» / «Continue without signing in»; опрос тоже можно пропустить.

  5. Дождаться зелёного «Engine running» внизу слева в окне Docker Desktop.

  6. В новом терминале:

    docker --version

Для второго способа Docker Desktop должен быть запущен каждый раз. Чтобы не вспоминать, включите в настройках (шестерёнка) «Start Docker Desktop when you sign in».

Если Docker пишет про WSL или виртуализацию — см. таблицу в конце.

Шаг 9. Запустить базу данных

cd C:\dev\rubezh
docker compose up -d

В первый раз Docker скачает контейнеры — минута-две. Проверить:

docker compose ps

У rubezh-postgres-dev и rubezh-redis-dev в колонке STATUS должно быть Up ... (healthy); если starting — подождать полминуты и повторить. Дальше контейнеры поднимаются сами вместе с Docker Desktop, эта команда нужна один раз.

Шаг 10. Подготовить таблицы в базе

pnpm --filter backend-api prisma:deploy

Создаёт в пустой базе нужные таблицы. Лишний запуск ничего не ломает, поэтому его стоит повторять после каждого git pull. Если таблицы уже есть, ответ — No pending migrations to apply.

Над ответом может появиться рамка Update available с советом выполнить npm i .... Не выполнять: версии в проекте закреплены намеренно, а npm в этом репозитории ломает установку. Библиотеки ставятся только через pnpm install.

Шаг 11. Включить аккаунт, сохранения и лидерборд

Забеги сохраняются под аккаунтом. В обычном браузере Telegram не может подтвердить, кто вы, поэтому для локальной работы сервер пускает по имени из настроек. Сначала получите секрет для подписи входа — эта команда печатает 64 случайных знака:

$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); -join ($b | ForEach-Object { $_.ToString('x2') })

Скопируйте результат. Откройте .env:

notepad .env

и поменяйте четыре строки (искать — Ctrl+F). Вход включается самим секретом — отдельного флага у него нет:

JWT_ACCESS_SECRET="сюда — 64 знака из команды выше"
TELEGRAM_BOT_TOKEN="local-dev-no-bot"
AUTH_DEV_LOGIN="true"
VITE_AUTH_DEV_USER="dev-1:Tester"
  • TELEGRAM_BOT_TOKEN — здесь подойдёт любой непустой текст. Настоящий токен бота нужен только для запуска внутри Telegram и никуда не выкладывается.
  • dev-1:Tester — ваш id и имя в лидерборде, латиницей надёжнее. Начало dev- обязательно: так сервер отличает вас от игроков Telegram.
  • Строки PLAYTEST_* из старой инструкции больше ничего не делают — их можно удалить.

Сохранить (Ctrl+S) и закрыть Блокнот.

Шаг 12. Запустить игру вместе с сервером

Если сервер из шага 7 ещё работает, остановите его (Ctrl+C). Потом:

pnpm dev

Команда запускает в одном окне и сервер (backend-api), и игру (web-telegram). Когда появятся строки API запущен на http://localhost:4000 и Local: http://localhost:5173/, откройте http://localhost:5173. Теперь забеги сохраняются, а на вкладке «Рейтинг» есть лидерборд.

Красная строка POST /api/v1/events 404 в инструментах браузера (F12) — нормально: приём статистики на локальной машине выключен.

Каждый следующий день

cd C:\dev\rubezh
git pull                                  # забрать изменения команды из dev
pnpm install                              # докачать новые библиотеки, если появились
pnpm --filter backend-api prisma:deploy   # только для второго способа
pnpm dev                                  # второй способ; для первого — pnpm dev:telegram

Для второго способа Docker Desktop запускается до pnpm dev.

Если вы правили файлы сами и git pull ругается на конфликт — ничего не удаляйте и позовите владельца репозитория.

Если что-то пошло не так

Что видите Что делать
git, node, pnpm или docker — «не распознано как имя командлета» Программа не установлена или терминал открыт до установки. Закрыть терминал, открыть заново
«Невозможно загрузить файл ...pnpm.ps1, так как выполнение сценариев отключено в этой системе» Один раз выполнить Set-ExecutionPolicy -Scope CurrentUser RemoteSigned и ответить Y: так PowerShell разрешит запуск скриптов установленных программ, только для вашей учётной записи
corepack enable — EPERM: operation not permitted Терминал открыт не от администратора, см. шаг 3
ERR_PNPM_UNSUPPORTED_ENGINE / Unsupported engine Не та версия Node.js: node -v должна показать v22.22.3. Переустановить по шагу 2
Port 5173 is already in use / EADDRINUSE Сервер уже запущен в другом окне или завис после закрытия. pnpm stop, потом запустить снова
docker пишет error during connect или cannot find the file specified Docker Desktop не запущен. Запустить и дождаться «Engine running»
Docker Desktop: «WSL needs updating» / «WSL 2 installation is incomplete» В терминале от администратора wsl --update, затем перезагрузка
Docker Desktop: «Virtualization support not detected» В BIOS выключена виртуализация. Включить Intel VT-x или AMD SVM — у каждой материнской платы по-своему, искать по её модели
docker compose up — port is already allocated на 5432 или 6379 На компьютере уже стоит свой Postgres или Redis. Остановить его в «Службах» Windows или поменять POSTGRES_PORT / REDIS_PORT в .env вместе с портом в DATABASE_URL / REDIS_URL
Сервер падает с JWT_ACCESS_SECRET задан — вход включён, и ему нужны TELEGRAM_BOT_TOKEN и DATABASE_URL Не заполнен токен бота или адрес базы, см. шаг 11
Сервер падает с AUTH_ENABLED убрана или ADMIN_PANEL_ENABLED убрана В .env старая строка, которая спорит с ключом: вход и панель включаются секретом JWT_ACCESS_SECRET. Строку удалить
В рейтинге «Рейтинг работает, когда игра открыта в Telegram» Не задан VITE_AUTH_DEV_USER (шаг 11) или страница не обновлена после правки .env — F5
Белый экран, игра не грузится F12 → вкладка «Console». Скриншот красного текста вместе со скриншотом терминала — владельцу репозитория
После git pull что-то странное Remove-Item -Recurse -Force node_modules, затем pnpm install

Когда просите помощи, присылайте скриншот терминала целиком и команду, которую вводили: по одному «не работает» причину не найти.

Полезные команды

pnpm typecheck   # tsc -b по всем пакетам разом
pnpm lint        # eslint по всему репозиторию
pnpm test        # все тесты; интеграционные без тестовых Postgres и Redis пропускаются
pnpm build       # сборка всех пакетов/приложений
pnpm budget      # вес того, что уезжает на устройство, — после pnpm build
pnpm docs:check  # битые ссылки в документации, входит и в pnpm test

Перед PR проходят все пять команд гейта — typecheck, lint, test, build, budget: это то же, что проверяет CI (CLAUDE.md, «Сборка и проверка перед PR»).

Если после git pull что-то ведёт себя странно — переустановить зависимости:

Remove-Item -Recurse -Force node_modules; pnpm install

Пакеты ссылаются друг на друга через протокол workspace:*. Раскладка node_modules строгая: пакет видит только то, что объявил в своём package.json — это то, чем защищены границы слоёв из docs/15-engineering-standards.md §2.2.

Структура репозитория

/packages
  /shared-types      <- общие TS-интерфейсы (PlatformAdapter, EnemyDef и т.д.)
  /fx                <- курсы валют и пересчёт: ядро без игры, Nest и Prisma, собирается в JS
  /design-tokens     <- базовые токены дизайна: палитра, шрифты, радиусы, движение — общие для игры и панели
  /core-game         <- игровой движок (Phaser), контент как данные в src/content/*
  /app-shell         <- React-оболочка: экраны, дизайн-система, звук, состояние
  /adapter-telegram  <- реализация PlatformAdapter под Telegram WebApp SDK
  /adapter-max       <- реализация PlatformAdapter под MAX Bridge
  /adapter-vk        <- реализация PlatformAdapter под VK Bridge
/apps
  /web-telegram      <- Vite-сборка под Telegram (env=telegram)
  /web-max           <- Vite-сборка под MAX (env=max)
  /web-vk            <- Vite-сборка под VK (env=vk)
/backend
  /api               <- NestJS + Prisma + Redis, единая точка входа для всех платформ
/infra               <- Docker-образ бэкенда, шаблон туннеля frp
/scripts             <- проверки гейта: бюджет бандла, ссылки в доках, границы слоёв
/docs                <- вся проектная документация, читать с docs/00-README.md

Зоны ответственности по этим папкам между участниками команды — в docs/06-team-and-workflow.md §2.

Бэкенд публичный вместе с репозиторием — и это решение, а не недосмотр. Секрет антифрода не в коде проверок, а в их числах: пороги и окна задаются окружением прода и в репозиторий не попадают, умолчания в .env.example нарочно мягкие (docs/34-stage3-plan.md, Р7).

About

Кроссплатформенная HTML5-игра для Telegram, MAX, VK и браузера

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages