fishing-game/AGENTS.md

AGENTS.md

Игра — один файл index.html (HTML+CSS+JS, ~1380 строк): без сборки, зависимостей и бэкенда. Весь код в одном <script>, секции помечены комментариями. UI, комментарии и доки — на русском; при правках сохраняйте этот стиль.

Проверка (lint/typecheck отсутствуют)

1. Синтаксис: node tools/check.mjs — вынимает JS из index.html и прогоняет node --check (при ошибке показывает номер строки index.html).
2. Главный рубеж — плейтест:

   cd tests
   npm install   # puppeteer-core
   npm test      # = node test.js
   

   Ждать все PASS и exit 0. Сейчас проверок 54.
3. Браузерный плейтест (вкладка встроенного браузера Orca, через Orca CLI):

   node tests/orca-playtest.js   # из каталога репо; требует ЗАПУЩЕННЫЙ Orca app и orca-ide (или ORCA_CLI_COMMAND)
   

   Проходит тот же геймплей «вживую» в браузере (не headless) и пишет orca-*.png в каталог запуска. Если Orca app не запущен — пропустить и НЕ блокировать (главный рубеж — пункт 2). Подробности и подводные камни: docs/BROWSER-TESTING.md.
4. Скриншоты: node tests/shots.js пишет shot-*.png в каталог запуска (запускать из tests/); README ссылается на screenshots/ в корне — свежие скопировать туда. В headless нужен шрифт emoji (Noto Color Emoji), иначе в скриншотах квадраты.

Подводные камни

• tests/test.js берёт браузер из process.env.CHROMIUM || '/usr/bin/chromium-browser', а URL игры резолвит динамически от каталога репо (тот же паттерн, что в shots.js). Если тест падает на старте — поправьте имя/путь chromium под свой чекаут (переменная CHROMIUM).
• Тесты гоняют игру через внутренние глобалы в page.evaluate: state, save, biteTimer, reel, SPECIES, SPECIES_NIGHT, rod(), SHINY_CHANCE, forceBoss, stateBoss, bossPhase, dayPhase, pickSpecies(), setDayTime(), todayStr(), dateShift(), isoWeek(), achBonus() и имена состояний MENU/IDLE/CHARGE/CAST/WAIT/APPROACH/BITE/REEL/SNAP/CARD. Переименование любого из них ломает тесты молча — имена держать, либо обновлять тест в том же коммите.
• Ввод на Pointer Events (pointerdown/pointerup), а не touch/mouse — так тест управляет игрой мышью. Не заменять на тач-обработчики.
• Сейв: ключ localStorage fishing-save-v1. При изменении формата — миграцию добавлять в loadSave() (старые сейвы обязаны оставаться читаемыми).

Где крутить

• Баланс (рыба/удилища/приманки): константы SPECIES, RODS, LURES в начале скрипта.
• Ночь (M3): длительность суток DAY_LENGTH (сек), ночная таблица рыб SPECIES_NIGHT, фонарик — LURES id=4 (секция «M3: Цикл дня/ночи»).
• Босс (M4): тест-форс появления forceBoss, фазы боя stateBoss/bossPhase, босс-ветки в updateReel() (обрыв фазы) и SNAP в updateGame() (авто-переход), награда ×5 в catchFish().
• Сложность вываживания: updateReel().
• Награды (M2): шаблоны квестов QUEST_TPLS, награды стрика STREAK_REWARDS, достижения ACHIEVEMENTS — секция «M2. Награды» после сейва.

Запуск и публикация

• Dev-сервер: python3 -m http.server 8000; игра так же работает с file://.
• Процесс разработки, публикация в Gitea, гигиена секретов: docs/DEVLOG.md.