Движок текстовой игры (RPG, экономика, казино)

• /start → в game_tap записывается «__open» → запускается шаг «Игровой движок»
• Движок загружает игрока (OBJECT-переменная контакта game_player) и общее состояние (OBJECT-переменная бота game_world) через ctx.chatState.atomicUpdate, применяет нажатую команду, обновляет рейтинг и возвращает текст экрана и JSON-массив подписей кнопок
• «Экран игры» показывает текст и эти подписи как динамические кнопки; нажатие записывает подпись в game_tap и возвращает к движку
• Движок хранит соответствие «подпись → команда» для кнопок на экране, поэтому старая или неизвестная подпись просто открывает главный экран

• Впишите свой Telegram id в переменную приложения game_admin_id (сначала там 0 — никто), чтобы открыть админ-панель.
• Опубликуйте бота и отправьте /start в Telegram — состояние игры сохраняется только в опубликованной версии.
• Цены, работы, товары и тексты меняются в файле rules.ts внутри шага «Игровой движок».

Полезно знать

• Это шаблон для игр с состоянием: ОДИН шаг CUSTOM_CODE + ОДНО сообщение с динамическими кнопками + ОДНА петля. Не делайте блок на каждый экран, товар или работу — это не масштабируется, и любое изменение трогает граф.
• Разделите код на файлы: index.ts (вход, чтение и запись состояния), rules.ts (всё, что владелец настраивает: цены, работы, товары, тексты), game.ts (что делает нажатие), screens.ts (текст и кнопки экранов), state.ts, types.ts. Импорты относительные ('./rules'). Тексты для пользователя — в rules.ts, на всех языках бота.
• Состояние игрока — в OBJECT-переменной контакта, общее (рейтинг, кланы, настройки) — в OBJECT-переменной бота, и пишутся ТОЛЬКО через ctx.chatState.atomicUpdate: при конфликте он повторяет попытку, поэтому функция обновления должна быть синхронной и чистой — случайные числа тяните заранее. chatState читает ОПУБЛИКОВАННУЮ версию: опубликуйте бота перед проверкой в Telegram.
• Механики со временем (зарплата, голод, энергия) считаются при каждом нажатии по сохранённым отметкам времени — планировщик не нужен. Ограничьте, сколько офлайн-времени засчитывается.
• Подписи кнопок — это то, что нажимает пользователь; при отрисовке сохраняйте соответствие «подпись → команда» в состоянии игрока и разбирайте нажатие через него. Подписи на одном экране должны быть уникальными.
• Чтобы добавить функцию, меняйте один файл через apply_actions update_custom_code_file — не пересылайте весь шаг. Код, который не компилируется, отклоняется при применении.
• Админ-панель видна только игроку, чей Telegram id совпадает с переменной приложения game_admin_id; пока там 0 (никто), панель скрыта.
• Действия админа над ДРУГИМ игроком (выдать или списать деньги, сбросить) не требуют живого бота: движок разбирает «/give @user 100», затем const target = await ctx.contacts.findByUsername('@user') — { contactId, platformId } или null, если этот человек ни разу не писал боту (скажите об этом админу). Баланс в отдельной NUMBER-переменной контакта меняется через await ctx.contacts.increment(target.contactId, 'balance', 100). В этом примере деньги лежат внутри объекта game_player, а ctx.chatState меняет его только у ТЕКУЩЕГО игрока, поэтому админ записывает выдачу в game_world.grants[target.contactId] внутри atomicUpdate мира, а движок игрока переносит её в баланс при его следующем нажатии.

Частые вопросы

• О чём игра — жизнь в городе, ферма, фэнтези-RPG, бизнес-тайкун, казино?
• Какие механики важны в первую очередь: деньги и работа, магазин, казино, кланы и территории, потребности вроде еды и здоровья?
• Должно ли игровое время идти быстрее реального (например, 1 игровой месяц = 3 минуты)?
• Кто может менять цены и настройки в админ-панели?

Что важно помнить

• Не делайте блок на каждый экран, товар или работу — используйте движок.
• Не храните состояние игры во множестве отдельных записей SET_VARIABLE — один OBJECT на игрока и один общий, с атомарным обновлением.
• Не выпускайте экран-заглушку («скоро здесь будет…») для механики, которую просил пользователь: сделайте её или прямо скажите, что её пока нет.
• Не вызывайте Math.random() и побочные эффекты внутри функции обновления atomicUpdate — она может выполниться несколько раз.
• Не показывайте в админ-панели настройку, которую игра на самом деле не использует.