Игра на Godot 4 из-под Claude Code

Скил собран из реального опыта: полноценная 3D-игра (5 режимов, сезоны, погода,
день/ночь, пост-шейдеры, звук, бот-игрок, standalone .exe) написана целиком
агентом, без единого клика в редакторе Godot.

Главный принцип: код-первый (code-first)

Вся сцена строится из GDScript в _ready(). .tscn — заглушка на 5 строк.

Main.tscn   # Node3D + script — и всё
Main.gd     # весь мир: свет, камера, меши, материалы, UI, звук, логика

Почему это не «костыль», а лучший вариант именно для агента:

• Редактор Godot — GUI. Кликать в нём нельзя, а .tscn-диффы огромного дерева
  нечитаемы и легко ломаются при ручной правке.
• Всё состояние мира в одном текстовом файле → любую правку видно в git diff,
  можно грепать, рефакторить, ревьюить.
• Процедурная генерация (поле, декор, дороги) всё равно нужна — значит,
  половина сцены и так в коде. Разделять её на «то в редакторе, то в коде» хуже.

Ставь .tscn только там, где ресурс реально приходит извне (импортированная
модель, .wav). Всё, что можно собрать MeshInstance3D.new() — собирай в коде.

Исключение: если пользователь сам работает в редакторе и хочет там что-то
править руками — спроси, прежде чем уводить это в код.

Старт нового проекта — чеклист

1. project.godot (минимум — см. references/project-setup.md), Main.tscn,
   Main.gd, icon.svg, .gitignore (.godot/, build/).
2. Godot-бинарник: Godot_v4.x-stable_win64.exe (GUI) и
   ..._win64_console.exe (для CLI — пишет вывод в stdout). Если их нет —
   спроси у пользователя путь или попроси скачать; не качай сам.
3. Сразу проверь, что пустой проект запускается (см. ниже), и только потом пиши логику.

Цикл разработки и проверки

# запуск
./Godot_v4.7-stable_win64.exe --path godot

# проверка без окна: скрипт парсится, _ready() не падает
./Godot_v4.7-stable_win64_console.exe --headless --path godot --quit-after 60

# standalone .exe (нужны export templates, ставятся один раз из редактора)
./Godot_v4.7-stable_win64_console.exe --headless --path godot \
  --export-release "Windows Desktop" build/Game.exe

Проверяй себя сам, не сваливай тест на пользователя:

• --headless --quit-after N ловит 90 % ошибок: синтаксис, опечатки в API,
  падения в _ready(), warnings. Гоняй после каждой существенной правки.
• Скрытые флаги для быстрого входа в режим — очень окупаются:

  if "--td-test" in OS.get_cmdline_user_args():
      call_deferred("start_mode", "tower")

  Запуск: Game.exe -- --td-test (двойное -- обязательно — иначе флаг съест сам Godot).
• Само-проверки алгоритмов печатай в stdout под флагом (print("[bp] ok=", ...))
  — это дешёвые юнит-тесты без фреймворка.
• Держи в углу Label с Engine.get_frames_per_second() — регресс по FPS видно сразу.
• Визуал (цвет, композицию, «красиво/некрасиво») headless не проверить.
  Тут честно проси пользователя посмотреть и опиши, что именно оценить.

Что читать дальше

Файл	Когда
references/project-setup.md	завести проект, экспорт .exe, структура файлов
references/code-first-scene.md	архитектура скрипта, _ready-билдеры, UI, ввод, сохранения
references/visuals-3d.md	меши из кода, материалы, шейдеры, пост-эффекты, небо, частицы
references/performance.md	MultiMesh, LOD, draw calls — когда просело FPS
references/audio.md	звук: пул плееров, процедурные WAV, 3D-панорама, зацикливание
references/gdscript-gotchas.md	грабли GDScript 4 и переименования из Godot 3

Рабочие привычки

• Один большой скрипт — нормально до ~5k строк, если он строго разбит на
  секции комментариями-баннерами и _build_* / _update_* функциями. Дробить
  на десяток файлов ради «чистоты» на этом масштабе только мешает грепать.
• Числовые константы игры — в var/const наверху файла с комментарием, что
  они делают. Пользователь будет их крутить, ему нужен один экран с ручками.
• Всё, что игрок может настроить — выводи в UI слайдером/кнопкой сразу, не
  прячь в код. Настройки сохраняй в user://*.cfg через ConfigFile.
• Комментарии пиши на языке пользователя (в этом проекте — русский).
• В коммит-сообщение по перформансу клади замеры «было → стало» и железо.