squad-proto/docs/08-decisions.md

08 — Решения и отклонения от спека

Спек в разделе 12 требует: раздел 6 реализуется как написано, а если считаешь, что где-то ошибка — сначала скажи, потом делай. Здесь перечислено всё, что отличается от буквы спека, с причиной и замерами.

Отклонения разделены на две группы: содержательные (меняют поведение) и структурные (не меняют).

---

A. Содержательные

A1. Пуля не летит дальше проверенного отрезка

Спек: 6.9 — снаряд со скоростью 22 юнита/с. Сделано: время жизни пули = длина отрезка «дуло → цель» / скорость, а не дальность оружия / скорость.

Почему. LaneClear проверяет отрезок до цели. Если цель успевает умереть от чужой пули, снаряд летит дальше — в пространство, которое никто не проверял. Ровно так возникало последнее упорное попадание по своим: агент стоял внутри кучки мишеней, пуля прошла место умершей мишени насквозь и нашла его.

Замер: до фикса — 1 попадание за 300 с, стабильно воспроизводимое (t=94.49, #1 -> #2 @ (30.6,21.7)); после — 0 за 300 с.

A2. Спуск учитывает время полёта пули (AllyInterceptsShot)

Спек: 6.3 проверяет линию в момент выстрела. Сделано: дополнительно проверяется сближение пули и союзника как двух движущихся точек на всём времени полёта, с радиусом безопасности, растущим со временем (shotPredictSlack — запас на то, что союзник может и повернуть).

Почему. 6.3 даёт мгновенный снимок, а 6.9 делает пулю реальным снарядом: до 0.4 с полёта, за которые союзник проходит больше метра. Союзник, честно чистый в момент нажатия, спокойно входит в коридор уже после выстрела. Реактивное расступание (6.6) этот случай не закрывает по определению — оно срабатывает, только когда тело уже в линии.

Само правило 6.3 при этом не ослаблено: это дополнительное условие спуска, а не замена. LaneClear продолжает использоваться и в целеуказании, и в оценке кандидатов, и в реестре линий — в том виде, как написано в спеке.

Замер: журнал попаданий показывал, что жертва всегда была ADVANCING — то есть именно вбегала под летящую пулю.

A3. В реестр линий попадают линии, перекрытые своим

Спек: 6.6 — «список активных линий огня — сегментов от стреляющих агентов». Сделано: линия регистрируется и тогда, когда у агента есть цель в радиусе, стена не мешает, а мешает только свой (Agent::laneIntent).

Почему. При буквальном прочтении механика самоотменяется: стоит кому-то влезть в линию — стрелок теряет линию, перестаёт быть «стреляющим», отрезок исчезает из реестра, и перекрывшего ничто не выталкивает. Сектор обстрела не освобождается никогда, а обещание 6.6 («отряд сам расплывается, освобождая сектора обстрела») и критерий 11.4 становятся недостижимыми.

Замер: FIRE UPTIME на маршруте вырос с 33 % до 49 %, худший uptime на стоянке — с 38 % до 51 %.

A4. Резерв линии шире порога блокировки (laneReserveScale = 1.8)

Спек: 6.6 — импульс, если dist < bodyRadius + laneHalfWidth + SAFETY_MARGIN. Сделано: импульс расступания начинается на laneReserveScale шире этого порога. Сам порог блокировки в 6.3 не тронут.

Почему. Раздел называется «Резервирование линий». Если отжимать агента ровно с той границы, за которой он уже блокирует выстрел, — это не резерв, а реакция постфактум: агент успевает войти в сектор, где летит пуля.

Замер (300 с, с A1 и A2):

laneReserve	FRIENDLY_HITS	худший uptime на стоянке
1.0 (буква спека)	1	42.5 %
1.4	0	50.0 %
1.8 (принято)	0	50.4 %

A5. Касательная составляющая обхода стен (wallSlide)

Спек: 6.7, слой 4 — «wallAvoidance + скольжение вдоль стен при коллизии». Сделано: помимо скольжения при коллизии, WallAvoidForce добавляет касательную силу в сторону цели, когда стена стоит между агентом и целью.

Почему. Чисто отталкивающее избегание даёт классический локальный минимум: seek тянет вперёд, отталкивание держит — агент залипает в «тени» препятствия. В прогонах это ловилось буквально: агент оставался в северной комнате (y=12), когда отряд уже стоял на арене (y=26).

A6. Агент без целей в радиусе возвращается в строй

Спек: случай не описан. 6.5 запускает решатель, когда линии нет, но не говорит, что делать, если стрелять вообще не по чему. Сделано: если решатель не нашёл ни одной цели в пределах weaponRange + ring3, postPos = слот строя.

Почему. Иначе отставший агент стоит на месте вечно: в HOLDING он идёт только к postPos, а postPos равен его же позиции.

A7. Дуло считается в сторону цели, а не по facing

Спек: 6.3 — «muzzle() — точка в 0.3 юнита от центра агента по facing». Сделано: для проверки линии и для спавна пули дуло считается по направлению на цель; выстрел разрешён только когда ствол доведён до цели с точностью ±5° (aimToleranceDeg).

Почему. facing доворачивается плавно и на шаг отстаёт от направления на цель. Если проверять линию по одному направлению, а стрелять по другому, пуля летит не по проверенному отрезку — то есть гарантия «не сквозь своих» перестаёт быть гарантией. Сейчас проверенный отрезок и траектория пули — буквально один и тот же отрезок.

A8. Пуля не бьёт собственного стрелка

Спек: 6.9 — «коллизия со всеми капсулами, включая союзников». Сделано: стрелок исключён из коллизий своей пули.

Почему. Дуло вынесено на 0.3 юнита при радиусе тела 0.28 — пуля стартует почти вплотную к своему же телу. Самопопадание было бы вырожденным шумом в FRIENDLY_HITS, главной метрике корректности. Все остальные капсулы, включая союзников, проверяются как написано.

A9. Северная кучка мишеней стоит напротив прохода

Спек: 4 — 12 мишеней кучками, конкретные места на усмотрение реализации. Сделано: кучка из 3 мишеней в северной комнате поставлена напротив прохода x=30..31, так что из коридора до неё есть чистая линия.

Почему. Спек называет узкий проход важным тест-кейсом, а критерий 11.6 требует, чтобы в проходе отряд вытягивался в колонну и стрелял только передний. Без цели, простреливаемой сквозь проход, проверять нечего.

A10. Вторичные цели в HOLDING при ручном прицеливании

Спек: 6.8 — флаг freeFireSecondary описан только для ADVANCING. Сделано: буквально — в HOLDING агент без линии до назначенной цели молчит и перестраивается решателем, по вторичным целям не стреляет.

Почему. Иначе агент нашёл бы вторичную цель, получил бы hasLane, и решатель для него никогда бы не запустился — то есть требование «в HOLDING перестраивается через решатель» не выполнялось бы.

A11. Туман войны и освещение вопреки разделу 12

Спек: 12 — «не добавлять освещение, туман войны». Сделано: добавлено и то, и другое.

Почему. Заказчик изменил требования: прототип разворачивается в хоррор, где ограниченный обзор и темнота — не украшение, а основа подачи. Правила стрельбы (раздел 6) при этом не тронуты ни одной строкой, критерии приёмки остались зелёными. Устройство слоя — 10-atmosphere.md.

A12. Конус зрения не влияет на ИИ

Сделано: у агента есть конус обзора для КАРТИНКИ, но выбор целей и стрельба по-прежнему работают по LOS и дальности оружия.

Почему. Если завязать целеуказание на видимость, меняются все критерии приёмки, а отряд начинает «слепнуть» от поворота ствола — при том что LaneClear и так требует чистой линии, то есть отсутствия стены. Чтобы стрельба в темноту не выглядела абсурдом, мишень показывается, если освещена или если по ней уже работает кто-то из отряда.

A13. Shift — рывок, а не медленный шаг

Спек: 5 — «Shift (удерж.) — медленный шаг». Сделано: базовая скорость снижена с 3.2 до 2.0, а Shift даёт рывок 3.2.

Почему. Заказчик просил «менее казуальное управление, помедленнее». Медленный шаг при уже медленной базе — мёртвая клавиша. Инверсия сохраняет обе скорости из спека (2.0 и 3.2), но делает осторожность режимом по умолчанию, а спешку — осознанным решением игрока. Побочный эффект: проверка спуска на время полёта пули обязана считать по МАКСИМАЛЬНОЙ скорости (MaxAgentSpeed()), иначе рывок союзника не учитывается и возвращаются попадания по своим.

A14. Дальность оружия 9.0 -> 7.2

Сделано: минус 20 % по требованию заказчика; вместе с ней отмасштабированы minEngageDist (2.0 → 1.6) и кольца решателя (0.8/1.6/2.4 → 0.7/1.4/2.1), а старт отряда сдвинут в (26.5, 26.5) ближе к кучке мишеней.

Замер: без сдвига старта и масштабирования колец сокращение дальности само по себе давало 1 попадание по своим за 300 с и просадку uptime — агенты сбивались в кучу у цели. С пакетом целиком: 0 попаданий, uptime в стоячем бою 100 %.

A15. candMinAlly 0.55 -> 0.60

Порог «кандидат слишком близко к союзнику» был меньше диаметра тела (2 × 0.28 = 0.56), то есть допускал позиции, где агенты физически пересекаются.

A16. Клинок союзникам урона не наносит вообще

Спек: ближнего боя не описывает. Сделано: сектор удара повторяет правило 6.3 в угловой форме — свой в секторе — не бить. Но урон применяется только к мишеням: даже влезший под лезвие союзник не получает ничего, взмах просто обрывается.

Почему. Соблазн был сделать «сильную» версию: клинок бьёт всех, а от попаданий по своим спасает дисциплина сектора. Но у клинка нет времени полёта, за которое можно передумать: союзник входит в дугу за 1/60 с уже после того, как взмах начат, и в этот момент отменять нечего. «Сильная» версия означала бы FRIENDLY_HITS > 0 в любой плотной свалке, то есть провал главного критерия прототипа ради механики, которой в спеке нет.

Обрыв взмаха даёт то же самое ощущение (боец отдёргивает клинок, серая вспышка, MELEE_ABORT в метриках) и при этом не может сломать критерий 11.2.

Замер: 81 взмах за 30 с в плотной свалке, FRIENDLY_HITS = 0, 16 взмахов оборвано.

A17. Старт замаха смотрит на союзника вперёд

Сделано: MeleeArcClear проверяет союзника в двух точках — где он сейчас и где будет через windup + strike. Ровно та же поправка, что A2 для пули.

Почему. Взмах живёт 0.30 с, за которые союзник проходит полметра. Проверять только текущее положение — значит начинать удары, которые всё равно придётся обрывать.

Замер (сценарий M7, 30 с): без поправки и без резерва дуги — 21 оборванный взмах из 77; с поправкой и резервом — 16 из 81, попаданий 81 против 81, убийств 23 против 23. То есть взмахов стало больше при том же результате.

A18. Резерв в реестре линий получил явную полуширину

Сделано: у FireLane появилось поле reserve. Линия огня по-прежнему берёт ширину из правила 6.3, клинок задаёт свою — долю бокового размаха сектора (meleeReserveFrac 0.55).

Почему. Клинок резервирует отрезок вдоль оси удара, а поражает сектор ±50°. Союзник, отжатый строго перпендикулярно оси, попадал ровно во фланг дуги — то есть механизм расступания работал против себя.

Замер: meleeReserve 0 → 0.55 дало 16 оборванных взмахов вместо 21 при большем числе взмахов, а худший FIRE UPTIME на стоянке маршрута — 23.3 % вместо 0 % (стрелки перестали стоять в дугах и молчать).

A19. Жёсткая граница огневой позиции (postLeash)

Спек: 6.5 — цена за удаление от якоря. Сделано: дополнительно кандидат дальше cohesionRadius + postLeash от якоря отбраковывается совсем.

Почему. Цена — мягкая: линия огня стоит 100 очков, а уход на 1.5 юнита за круг — 36. Решатель всегда выбирал линию, и отряд расползался.

Замер: максимум удаления стрелка от диска 3.65 → 2.81 юнита. При этом FIRE UPTIME на 180-секундном маршруте не упал, а вырос: на стоянках у мишеней 82.9 / 93.2 / 90.7 / 86.0 % — плотный отряд перекрывает друг другу линии реже, чем расползшийся.

A20. Мишени — тела, и они получают отдачу

Сделано: слой движения TargetPushForce (мишень расталкивает агентов) и импульс от удара с возвратом на исходное место (Target::home).

Почему. Без расталкивания боец стоит внутри того, кого рубит, и удар не читается вообще. Без отдачи попадание в упор визуально не отличается от промаха. Возврат на home обязателен: расстановка уровня захардкожена, и уползание мишеней поломало бы все замеры разом. Респавн дополнительно ставит pos = home.

A21. Критерий 11.6 считает только выстрелы вперёд

Было: тест требовал, чтобы в коридоре передний агент стрелял минимум вдвое чаще хвостовых, и считал ВСЕ выстрелы внутри прохода.

Стало: считаются только выстрелы по ходу движения. Выстрелы назад выводятся в отчёт отдельно.

Почему. Диагностика DIAG показала, что почти все «нарушения» — это хвостовой агент, стреляющий назад, в оставленную позади комнату, по совершенно другой цели. Впереди по такой линии никого из отряда нет по построению, и к правилу «не стрелять сквозь своего» это отношения не имеет. Порог ловил не поведение, а геометрию расстановки мишеней.

Замер: на прежней базе тюнинга новый счёт даёт 4/0 (было 12/4), на текущей — 5/0. То есть критерий стал строже, а не мягче: вперёд хвост не стреляет вообще.

---

B. Структурные (поведение не меняют)

B1. Дополнительные файлы

Спек перечисляет структуру проекта; добавлены четыре файла:

Файл	Зачем
game.h/.cpp	склейка подсистем и порядок шага. Без него это переехало бы в main.cpp, а спек требует, чтобы там были только окно и цикл
render/scene.h/.cpp	проход по полу и список сортировки; отдельно от iso.h, который остаётся чистой математикой
core/input.h	InputState нужен и main.cpp, и симуляции, и headless-прогонам
debug/harness.h/.cpp	прогоны --headless / --accept
sim/loadout.h	класс оружия и его параметры; сюда приедут разные пушки и апгрейды
ai/melee.h/.cpp	ближний бой; зеркало firing_solver для угловой геометрии

B2. У Sprite есть точка привязки

Спек: Sprite { int w, h; std::vector<uint32_t> px; }. Добавлены поля ax, ay — точка внутри спрайта, совмещаемая с проекцией мировой позиции. Иначе смещения пришлось бы размазывать по коду отрисовки для каждого типа спрайта.

B3. Параметры оружия синхронизируются из Tuning каждый шаг

Agent::weapon существует как в спеке, но перед движением поля копируются из g_tune (SyncLoadoutFromTuning). Без этого runtime-подкрутка (раздел 8 спека) не влияла бы на уже созданных агентов. Состояние ближнего боя — фаза, таймеры, цель — при этом не трогается: копируются только параметры.

B4. Dev-инструменты

--headless, --accept, --probe, --set, --shot, тумблеры --no-solver / --no-laneavoid. В спеке их нет; они не влияют на игровую сборку и нужны, чтобы критерии приёмки из раздела 11 проверялись цифрами, а не на глаз.

---

Что осталось честно неидеальным

• FIRE UPTIME считает «нет живой цели в радиусе» простоем. На маршруте между комнатами это даёт низкие значения, которые к качеству ИИ отношения не имеют.
• SETTLE TIME по той же причине растёт, если отряд остановился там, где стрелять не по чему; в общем прогоне попадаются значения до 5.7 с. В обстановке, к которой относится критерий 11.1 (мишени в радиусе), — 0.02 с.
• Пути агентов чисто локальные, без поиска пути. Отряд проходит узкие коридоры, но лабиринт с тупиками не осилит — это вне рамок прототипа.