squad-proto/docs/10-atmosphere.md

10 — Хоррор-слой: свет, туман войны, трассеры, напряжение

Весь этот слой — render-only. Симуляция о нём не знает: RenderGame принимает const Game&, поэтому ни свет, ни трассеры, ни тряска камеры физически не могут изменить состояние симуляции. Headless-прогоны (--accept, --headless) View не создают вообще, и цифры приёмки остаются цифрами симуляции.

Раздел 12 исходного спека запрещал освещение и туман войны. Заказчик изменил требования — теперь это ядро подачи. Правила стрельбы (раздел 6) не тронуты.

Порядок кадра

Clear(чёрный)                       ступень 0 рампы == цвет очистки
  -> свет и туман (Lighting::Update)
  -> пол: BlitShaded, тёмные тайлы пропускаются
  -> список сортировки: стены, мишени, агенты — тоже BlitShaded
  -> глаза мишеней (аддитивно)
  -> трассеры, вспышки дула, искры (аддитивно)
  -> ОДИН слитый пост-проход: виньетка, зерно, сердцебиение
  -> Present
  -> debug-оверлей (raylib, dev-only, F1)

Почему свет вплавлен в блит, а не сделан пост-проходом

Соблазн очевидный: пройти по 129600 пикселям, для каждого получить мировую точку через iso::ScreenToWorld и умножить на освещённость. Так делать нельзя.

Спрайт стены имеет привязку ay = TILE_HALF_H + TILE_H = 24, то есть верхняя грань поднята на 16 px над ромбом своего тайла. Обратная проекция этого пикселя даёт ScreenToWorld(0, -16) = (-1, -1) — ровно соседний тайл на северо-запад. Пост-проход осветил бы крыши стен чужой видимостью: чёрные крыши на освещённых стенах и светящийся ореол на тайл северо-западнее каждой стены. Чинится это только буфером высот на пиксель, то есть честным depth-буфером, которого в проекте нет и заводить его ради этого не стоит.

Поэтому свет модулирует цвет на этапе блита спрайта: спрайт целиком светится от своего тайла, и артефакт исчезает конструктивно, без единой проверки.

Модель света

Одна скалярная величина на точку мира плюс рампа — таблица g_shadeLut[32][3][256], переводящая уровень в цвет (подход COLORMAP из Doom). Цветокоррекция зашита в таблицу: в полумраке картинка уходит в холодный синий, на свету нейтральна, во вспышке выбивается в тёплый пересвет. На пиксель остаются три выборки из таблицы и ноль умножений.

tile = min(1, max(память, видимость * sightBrightness) + вспышки)

Состояние	Значение	Как выглядит
никогда не видели	0	чистый чёрный, тайл вообще не рисуется
видели раньше	fogMemoryLevel	тускло и холодно, сущностей нет
видно сейчас	sightBrightness	нормальная яркость
вспышка выстрела	выше	тёплый пересвет

Диапазон выше sightBrightness намеренно зарезервирован под динамический свет: выстрел всегда «выбивает» кадр вверх и в тепло.

Билинейка без швов

Узловая сетка 49×49 (corner), узел = среднее смежных тайлов. Патч света на тайл раскладывается в координатах спрайта без перекрёстного члена:

Bu = c10-c00,  Bv = c01-c00,  K = c00-c10-c01+c11
a = c00 - (Bu-Bv)/2 - K/4      b = (Bu-Bv+K)/TILE_W     c = (Bu+Bv)/TILE_H
e = -K/(TILE_W*TILE_W)         f =  K/(TILE_H*TILE_H)
L(px,py) = a + b*px + c*py + e*px^2 + f*py^2

Это точная билинейка по четырём вершинам ромба: подстановка (16,0), (32,8), (0,8), (16,16) даёт ровно c00, c10, c01, c11. Значит на общем ребре двух соседних тайлов значения совпадают и швов нет. По строке считается прямыми разностями — во внутреннем цикле два сложения на пиксель.

Блочность добивают четыре вещи: узловая сетка, точная билинейка, временное сглаживание (fogFadeRate) и упорядоченный дизеринг Байера 4×4 — 32 ступени рампы выглядят как ~200, полос не видно.

Видимость

Для каждого агента перебираются тайлы в квадрате радиуса обзора; для каждого — затухание по дальности × max(конус взгляда, круговой «личный» ореол), затем проверка LOS уже существующим Tilemap::RaycastBlocked. Рейкаст делается последним: дальность и конус отсекают большинство тайлов даром.

Стену нельзя проверить лучом до её центра — DDA считает вход в саму стену перекрытием. Поэтому стены освещаются отдельным проходом: берут максимум от соседей-нестен, WALL_LIGHT_PASSES = 3 раза с затуханием. Без этого разделитель y=13..15 толщиной три тайла остаётся чёрным изнутри, и его южная грань висит в пустоте.

Инвариант: стена никогда не темнее самого яркого соседа-пола. Иначе тёмная стена будет пропущена как «ступень 0», и сквозь её силуэт проступит освещённый пол тайла (tx−1, ty−1), который рисуется раньше по глубине.

Конус зрения и ИИ

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

Трассеры

Физика пули не тронута: снаряд летит ровно по проверенному отрезку, правило «не стрелять сквозь своих» и FRIENDLY_HITS = 0 не задеты. Менялся только вид.

• штрих от pos назад по вектору движения на tracerLength, но не дальше точки вылета — AddBeam рисует ядро с градиентом цвета и боковым ореолом;
• вспышка у дула — AddGlowDisc + короткий язык пламени, muzzleTime;
• искра попадания — своя для стены, цели, убийства;
• пурпурная искра = попадание по своему. Это не украшение, а индикатор: в норме её не должно появиться ни разу.

Всё аддитивно (AddSat), поэтому светится и поверх темноты — трассер сам себе источник света.

Дуга клинка

DrawMeleeArcs в src/render/fx.cpp. В отличие от трассеров, дуга читается прямо из состояния агентов, а не из журнала событий: фаза удара живёт десятые доли секунды и попадает в каждый кадр, а привязка к живой позиции важнее — боец в момент удара едет вперёд рывком.

• замах — холодная стальная дуга уводится назад за край сектора и разгорается. Это телеграф, и он обязан быть виден;
• удар — серп из четырёх концентрических дуг: внешний край раскалён, внутренние тускнеют к рукояти. Одна линия на 480×270 читается палкой, четыре — взмахом. Хвост — доля пройденной дуги, а не вся: серп, а не кольцо;
• восстановление — серп стоит на месте и быстро гаснет.

В изометрии круг — эллипс, поэтому дуга набирается сэмплами мировых точек (AddWorldArc), а не экранной окружностью.

Через журнал идут только дискретные события: MELEE_SWING (вспышка света), MELEE_HIT (оранжевая искра, сильная отдача камеры — удар всегда в упор), MELEE_ABORT (тусклая серая вспышка: свой влез под лезвие). Клинок дульной вспышки не даёт, но искры от удара освещают не хуже — иначе весь ближний бой шёл бы в кромешной темноте.

Подробности механики — 11-melee.md.

Канал «симуляция → эффекты»

sim/events.h: кольцевой журнал CombatEventLog. Симуляция только пишет, правила не читают, в headless передаётся nullptr.

Почему журнал, а не флаг Agent::fired: за один кадр рендера проходит до MAX_STEPS_PER_FRAME шагов симуляции. Флаг, выставленный на шаге 1 и затёртый на шаге 2, эффект не увидит. По той же причине Dread считает дельты накопительных счётчиков метрик, а не смотрит на флаги.

Напряжение (Dread)

Складывается из близости мишени, близости невидимой мишени (страшнее всего), толпы и того, сколько агентов вообще заняты боем. «Занят» — это линия огня у стрелка или цель в зоне удара у клинка: боец, достающий врага, беспомощным не выглядит и напряжение снимает так же. Сглаживание асимметричное: страх набегает быстро (dreadAttack), отпускает медленно (dreadRelease).

Кормит: глубину виньетки, амплитуду зерна, частоту сердцебиения, отдачу камеры. Отдача добавляется к scene.ox/oy сразу после scene.Begin — только там она согласована и с полом, и со списком сортировки, и с оверлеем.

Пост-проход

Один слитый цикл по 129600 пикселям: виньетка (статическое поле + таблица кадра), зерно с амплитудой обратно яркости (в тенях шумит, на свету чисто), давление сердцебиения. Света на входе нет — он уже вплавлен на блите.

Границы: индекс таблицы насыщения равен 128 + канал + шум, поэтому амплитуда зерна зажата 127 — иначе в Release пошли бы случайные яркие точки, которые легко принять за художественный замысел.

Псевдослучайность

render/noise.h — единственное место. Чистые хеш-функции без состояния: значение зависит только от координаты и номера кадра. Общего генератора нет, синхронизировать нечего, детерминизм симуляции не задет.

Цена

Замер на Intel Iris Xe, Release: 1.4–3.5 мс на кадр при бюджете 16.6 мс, то есть 8–21 %. Верхняя граница — когда память карты уже разведана и освещённых тайлов много; fps при этом держится 60. Симуляция — 1.9 мкс. Ни одна из оптимизаций (предзатенённые спрайты, пересчёт видимости через кадр, уменьшение числа ступеней рампы) не нужна.

Самое дорогое — не пост-проход, а BlitShaded сцены. Пропуск полностью тёмных тайлов это частично компенсирует: в тумане рисуется заметно меньше половины карты.

Аварийные тумблеры

F5 — выключить весь хоррор-слой (свет, туман, пост) и вернуть прежний кадр. F6 — показать диски обзора. Полезно, когда непонятно, баг это или темнота.