Кроссплатформенная 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. Каждый влитый 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 игра собирается в файл, а здесь файла нет. Игра — это веб-страница,
и показывает её маленький сервер, который вы запускаете у себя командой в
терминале. Пока он работает, игра открывается в браузере по адресу
http://localhost:5173 (localhost — «этот компьютер», в интернет ничего не
уходит). Правите код или данные, например
packages/core-game/src/content/enemies.ts, — страница обновляется сама,
пересобирать ничего не нужно.
Запустить можно двумя способами:
| Способ | Что работает | Что поставить |
|---|---|---|
| 1. Только игра | Вся игра: меню, забеги, настройки. Прогресс хранится в браузере | Git, Node.js, pnpm (шаги 1–7) |
| 2. Игра и сервер | То же плюс сохранение забегов на сервере и лидерборд | Всё из первого способа и Docker Desktop (шаги 8–12) |
Начните с первого: его хватает, чтобы играть и править баланс. Открыть игру внутри Telegram на телефоне пока нельзя — нужен туннель в интернет, его поднимает владелец репозитория.
Все команды вводятся в PowerShell — стандартном терминале Windows.
- Открыть: правый клик по кнопке «Пуск» → «Терминал». Появится окно с мигающим курсором.
- Команду из блока ниже скопировать и вставить (
Ctrl+Vили правый клик мышью), потомEnter. Одна строка — одна команда: вставляйте по одной и ждите, пока снова появится строка видаPS C:\...>. - Текст после
#— пояснение, терминал его пропускает. - Остановить то, что сейчас работает (например, сервер игры), —
Ctrl+Cв этом окне. - После установки новой программы закройте терминал и откройте заново, иначе он её не увидит.
Git скачивает проект и потом забирает обновления от команды.
-
Скачать установщик с https://git-scm.com/download/win («Click here to download»).
-
Запустить и на всех экранах жать «Next»: умолчания подходят.
-
В новом терминале проверить:
git --versionОтвет — что-то вроде
git version 2.51.1.windows.1.
Если привыкли к GitHub Desktop, клонировать можно и через него, но Git всё равно нужен: команды ниже его используют.
Node.js запускает сервер игры и все инструменты проекта. Нужна версия 22.22.3 или новее из линейки 22: на более старой установка остановится с ошибкой про версию.
-
Скачать установщик: https://nodejs.org/dist/v22.22.3/node-v22.22.3-x64.msi
-
Запустить, жать «Next». Галочку «Automatically install the necessary tools» не ставить — она ставит лишнее.
-
В новом терминале:
node -vДолжно быть
v22.22.3.
pnpm скачивает библиотеки, из которых собран проект, — примерно как Package Manager в Unity. Он уже лежит внутри Node.js, его нужно только включить.
-
Открыть терминал от администратора: правый клик по «Пуск» → «Терминал (администратор)» → «Да».
-
Выполнить:
corepack enable pnpm
Команда ничего не выводит — так и должно быть. Окно администратора закрыть.
-
Открыть обычный терминал:
pnpm -vЕсли спросит
Corepack is about to download ... Do you want to continue?, ввестиyиEnter. Ответ —10.15.0.
Если вместо версии ошибка «выполнение сценариев отключено в этой системе» — см. «Если что-то пошло не так».
Держите проект в короткой папке без русских букв и пробелов в пути и не
на рабочем столе: он часто синхронизируется с 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.
Copy-Item .env.example .env.env — настройки запуска вашей копии проекта. Он у каждого свой и в git не
попадает, так задумано. Пока в нём ничего менять не нужно.
pnpm installОдна–две минуты, несколько сотен библиотек. Заканчивается строкой
Done in .... Жёлтые предупреждения можно не читать, а красный ERR_... в
конце — ошибка, см. таблицу в конце.
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). Сервер перезапустится сам;
обновите страницу — инструменты появятся в меню ☰ → «Настройки» → «Для
тестировщиков».
Первый способ готов. Дальше — только если нужны сохранения на сервере и лидерборд.
Серверу игры нужны база данных (Postgres) и быстрое хранилище (Redis). Ставить их по отдельности не нужно: Docker запускает их готовыми в изолированных «коробках» — контейнерах, а Docker Desktop — программа, которая эти контейнеры держит.
-
Скачать с https://www.docker.com/products/docker-desktop/ → «Download for Windows — AMD64» (для ARM-процессора, например Snapdragon, — ARM64).
-
Запустить установщик, галочку «Use WSL 2 instead of Hyper-V» оставить.
-
Перезагрузить компьютер, если попросит.
-
Запустить Docker Desktop из «Пуска», принять соглашение. Входить в аккаунт не обязательно — «Skip» / «Continue without signing in»; опрос тоже можно пропустить.
-
Дождаться зелёного «Engine running» внизу слева в окне Docker Desktop.
-
В новом терминале:
docker --version
Для второго способа Docker Desktop должен быть запущен каждый раз. Чтобы не вспоминать, включите в настройках (шестерёнка) «Start Docker Desktop when you sign in».
Если Docker пишет про WSL или виртуализацию — см. таблицу в конце.
cd C:\dev\rubezh
docker compose up -dВ первый раз Docker скачает контейнеры — минута-две. Проверить:
docker compose psУ rubezh-postgres-dev и rubezh-redis-dev в колонке STATUS должно быть
Up ... (healthy); если starting — подождать полминуты и повторить. Дальше
контейнеры поднимаются сами вместе с Docker Desktop, эта команда нужна один
раз.
pnpm --filter backend-api prisma:deployСоздаёт в пустой базе нужные таблицы. Лишний запуск ничего не ломает,
поэтому его стоит повторять после каждого git pull. Если таблицы уже есть,
ответ — No pending migrations to apply.
Над ответом может появиться рамка Update available с советом выполнить
npm i .... Не выполнять: версии в проекте закреплены намеренно, а npm
в этом репозитории ломает установку. Библиотеки ставятся только через
pnpm install.
Забеги сохраняются под аккаунтом. В обычном браузере 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) и закрыть Блокнот.
Если сервер из шага 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).