Ферма для Telegram Mini App

Изометрическая ферма на чистом JavaScript (ES-модули). Рисует PixiJS (WebGL), а логика, движок и скелетная анимация — свои.

Запуск

Модули не работают через file://, поэтому нужен любой локальный веб-сервер:

• tools\run-local.cmd — двойной клик (нужен Node.js или Python), откроется http://localhost:8080
• или npm run dev

Полезные параметры адреса:

• ?debug — FPS, время кадра, фризы, уровень качества и масштаб рендера
• ?quality=low|mid|high — принудительно выбрать качество (проверка поведения на слабом телефоне)

Редактор карты (только для разработчиков)

Все игроки начинают с одной карты — assets/map.json. Редактировать её:

1. Запустить tools\editor.cmd (нужен Node.js) — откроется http://localhost:8080/editor.
2. Левая кнопка мыши — рисовать выбранным инструментом (трава, тропинка, вода, грядка, деревья, камни, лес, дом, колодец, старт призрачка, ластик, перенос). Правая кнопка — двигать карту, колесо — масштаб, [ ] — размер кисти, Ctrl+Z — отмена, Ctrl+S — сохранить.
3. «Сохранить» записывает assets/map.json прямо в папку проекта. Потом — коммит и пуш (push.cmd).

Редактор открывается только с этого компьютера (localhost) и в сборку dist для игроков не попадает. Жёлтая рамка — стартовый участок: дом, колодец, старт и хотя бы одна грядка должны быть в нём. После изменения карты у игроков сохраняется прогресс (монеты, уровень, участки, рюкзак), а деревья, камни, тропинки и постройки становятся как на новой карте.

Сборка

npm install
npm run build      # → dist/: один минифицированный бандл, CSS, index.html, картинки
npm run preview    # открыть собранную версию на http://localhost:8080

В бандл вшиты список картинок, иконок и стартовая карта: игра не делает за ними отдельных запросов. Папка dist/ в репозиторий не попадает: при каждом пуше в main GitHub Actions сам собирает игру и публикует её на GitHub Pages (.github/workflows/pages.yml). Адрес: https://matarener.github.io/FarmGames/

Подключение к Telegram

1. Адрес игры — GitHub Pages (выше) или любой другой HTTPS-хостинг с содержимым dist/.
2. В @BotFather: /newapp (или /mybots → Bot Settings → Menu Button) и укажите адрес index.html.
3. Внутри Telegram игра сама разворачивается на весь экран, отключает закрытие свайпом вниз, учитывает вырезы экрана и сохраняет прогресс в CloudStorage аккаунта (плюс localStorage).

Как устроено

index.html, style.css     точка входа и интерфейс (mobile-first, отдельные правила для планшета и ПК)
src/main.js               сборка всего вместе, экран загрузки, прогрев, запуск игрового цикла
src/engine/               свой движок
  Game.js                 цикл кадров, пауза в фоне, реже кадры в простое
  Renderer.js             размер холста, плотность пикселей, видимая область мира
  Camera.js               панорама, зум к точке, инерция, границы
  Input.js                тап / перетаскивание / щипок / колесо / наведение / WASD
  Perf.js                 мощность устройства, качество графики, 30 FPS на слабых, замер фризов
  Iso.js                  изометрия 2:1 (тайл 64×32)
  Pathfinding.js          A* на типизированных массивах
  Sprite.js               спрайты из кода, затемнение, загрузка картинок, ГПСЧ
  Audio.js                звуки и музыка, синтезируются на лету (без файлов)
src/skeleton/             своя скелетная анимация
  Skeleton.js             кости (аффинные матрицы), слоты, скины, порядок отрисовки
  Animation.js            ключевые кадры, кривые, события, плавное смешивание анимаций
src/game/
  data.js                 все таблицы и баланс: культуры, растения, предметы, дом, цены
  World.js                карта: клетки, объекты, участки 10×10, туман, сохранение разницы
  Farm.js                 правила фермы: тапы, действия, рост, урожай, рынок, рюкзак
  PixiScene.js            отрисовка всего мира через WebGL (PixiJS), атласы текстур
  artSprites.js           загрузка картинок художника (assets/art) и иконок
  shore.js                берег пруда (рисуется кодом поверх текстуры воды)
  Player.js, ghost.js     персонаж-призрачок: путь, очередь до 6 действий, кости и анимации
  Mover.js                режим «Переставить»: дом, колодец, грядки, тропинки, свои растения
  flora.js, wild.js       деревья и кусты: плоды, рост; дикая трава, кусты и саженцы
  inventory.js            рюкзак: чистые функции над состоянием
  planting.js             посадка культур и саженцев: чем платить, порядок и фильтры в окне выбора
  questData.js            таблицы заданий: сюжет и ветки, задания дня/недели/месяца, события по датам
  questRules.js           правила заданий (чистые функции): счёт, награды, смена дня, перенос старых сохранений
  quests.js               задания в игре: тосты, звуки, опыт по событиям правил
  giftData.js             подарки: разделы окна, дорожка ежедневных подарков на 30 дней
  giftRules.js            правила подарков (чистые функции): какой день, забрать, смена дня
  gifts.js                подарки в игре: звук, радость призрака, сохранение
  wheelData.js            колесо фортуны: сектора с призами и шансами, цены вращений
  wheelRules.js           правила колеса (чистые функции): сколько вращений осталось, какой сектор выпал
  wheel.js                колесо в игре (вращение и щелчки рисует окно в UI.js)
  hints.js                стрелка-подсказка к заданию на карточке
  bars.js                 полоски времени роста
  Save.js                 localStorage + Telegram CloudStorage (с нарезкой на части)
src/ui/UI.js              HUD, всплывающие меню, окна дома, рынка, рюкзака, заданий, подарков, колеса, настроек
src/editor/MapEditor.js   редактор карты (только локально)
src/telegram/             обёртка над Telegram WebApp API
assets/                   картинки художника и стартовая карта — см. assets/README.md
tools/                    локальный сервер, сборка, нарезка картинок, бот баланса,
                          проверка правил (node tools/test-quests.mjs, test-gifts.mjs,
                          test-wheel.mjs, test-planting.mjs)
docs/GDD.md               геймдизайн-документ

Правила игры (Farm, flora, wild, inventory, quests, World) отделены от звука и отрисовки, время и случайность передаются параметрами, контент — в таблицах data.js: так их потом можно перенести на сервер.

Задания

Сюжет и пять веток (Огород, Рыбалка, Лес и сад, Стройка, Торговля) идут параллельно, в каждой открыто одно задание. С 3 уровня добавляются задания дня, недели и месяца (сброс по московскому времени) и события по датам. Новое задание, ветка или событие — это строка в questData.js. Окно заданий открывается кнопкой «Задания» в нижнем меню (дом — в «Ещё»). На экране до трёх заданий: закреплённые игроком и текущее задание сюжета. С ?debug в адресе в «Настройках» есть кнопки «+1 день», «+7 дней» и «Событие» для проверки.

Подарки

Не объект на карте, а кнопка под монетами: она светится, пока есть подарок, который можно забрать, и пропадает, когда забирать нечего. Окно «Подарки» всегда открывается из «Ещё». В окне разделы «Ежедневные», «От друзей», «Приглашения», «События»; пока работают только «Ежедневные». Ежедневные — дорожка из 30 дней входа: раз в день (новый день в 00:00 по Москве, как у заданий) забирается подарок следующего дня, каждый 7-й день — кристаллы, 30-й — сундук с кристаллами, пропущенные дни не сгорают, после 30-го дорожка начинается заново. Награды — giftData.js. С ?debug в «Настройках» кнопка «Подарки заново» сбрасывает дорожку, «+1 день» — следующий день.

Колесо фортуны

Кнопка под подарком светится, пока есть бесплатное вращение на сегодня; окно всегда открывается из «Ещё» → «Колесо». Бесплатно — раз в день, за монеты — 5 раз в день (цена растёт), за кристаллы — без ограничений. Сектор решают правила (wheelRules.js, случайность параметром), окно докручивает колесо до него. Призы, шансы и цены — wheelData.js. С ?debug — кнопка «Колесо заново».

Производительность на слабых устройствах

• Вся графика — картинки художника в атласах видеокарты; игра открывается только когда всё загружено и прогрето (~2 с кадров за экраном загрузки), чтобы в игре не было подгрузок.
• Земля каждого участка — одна сетка ромбов; объекты не перерисовываются, пока не изменились.
• Разрешение рендера ограничено по классу устройства (×1 / ×1.5 / ×2). Если кадр не укладывается в бюджет, FPS ограничивается до 30.
• В простое игра рисует реже, а в фоне останавливается полностью.

Картинки

Как называются картинки, где лежат листы художника и как их нарезать — в assets/README.md.