Проверяемая 3D-игра на Godot 4

Дополняет скил godot-codefirst (код-первый подход, старт проекта, материалы и
шейдеры, звук, общая оптимизация). Здесь — то, чего там нет: как агенту
увидеть результат своими глазами, физика, корректность процедурного меша и
сеть. Всё проверено на 3D-хорроре в процедурном лабиринте (см. ORIGIN.md).

Главное правило

Не проси пользователя смотреть то, что можешь посмотреть сам.

Godot умеет отрендерить кадр в PNG и выйти. Один раз написанный
скриншот-харнесс (--shot=out.png + флаги) превращает «посмотри, пожалуйста»
в цикл, который агент крутит сам: правка → кадр → правка. Плюс A/B-флаги
(«выключи этот эффект») — главный инструмент диагностики визуальных багов.

G=./Godot_v4.7-stable_win64_console.exe        # console-сборка: пишет в stdout
$G --path game --headless --quit-after 600     # логика: падения, ошибки API
$G --path game --resolution 1280x720 -- "--shot=C:/tmp/f.png" "--shot-frames=150"

--headless для скриншота НЕ годится (нет рендера → чёрный PNG). Двойное --
обязательно: всё после него уходит в OS.get_cmdline_user_args().

Границы честности: композицию, цвет и «страшно/красиво» headless не проверяет.
Здесь проси пользователя посмотреть — и говори КОНКРЕТНО, что оценить.

Три диагноза, которые ставятся флагом за минуту

Симптом	Флаг	Что оказалось
пол чёрный, свет «не работает»	--shot-normals (нормаль цветом)	инвертированный winding
квадратные пятна на бетоне	--shot-no-macro	value noise с экстремумами на решётке
«SSAO не видно»	--shot-ssao-buffer	буфер живой, виноват чёрный ambient

Отладочный вывод внутрь шейдера (нормаль/UV/маска цветом) — самый быстрый
способ понять геометрию, когда картинка «просто неправильная».

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

Файл	Когда
references/self-test-harness.md	завести харнесс, A/B-флаги, юнит-тесты через stdout
references/physics-and-controller.md	FPS-контроллер, RigidBody-снаряды, коллизия из процедурного меша, баллистика ИИ
references/procedural-geometry.md	winding и нормали Godot, сглаживание, швы, толщина стен, декали, свет в тёмной сцене
references/perf-traps.md	prims взлетели в 50 раз: тени, прозрачность, режим «слабый ПК»
references/multiplayer.md	ENet, host-авторитет, детерминированный мир, чат и голос

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

• Каждая тяжёлая правка заканчивается прогоном --headless --quit-after N и
  кадром через --shot=. Не «кажется, работает», а лог и картинка.
• На каждый спорный эффект — флаг, который его выключает. Два кадра рядом
  отвечают на вопрос за минуту, гадание — за час.
• Замеры производительности клади в коммит парой «было → стало» и с железом.
• Всё процедурное — от явного сида (RandomNumberGenerator со смещением на
  подсистему). Это даёт воспроизводимый баг, стабильные A/B-кадры и мир,
  который в сети не надо пересылать.
• Комментарии и UI — на языке пользователя.