# Атмосфера и небо Атмосфера Parkan задаётся двумя связанными ресурсами: `sky.ske` хранит расписание, цвета и параметры, а `sky.wea` сопоставляет позиционные строки с материалами. Ресурсы сначала разбираются в `TypedAtmosphere` и `SkyMaterials`, затем на каждом кадре из расписания получается `AtmosphereFrame`. Модуль `fparkan-fx::sky` превращает этот кадр в данные для рендерера: постоянную геометрию купола, динамические цвета вершин, небесные слои, положение светил, туман и нижнюю границу освещения. ## Игровые сутки и смена дня и ночи Вызов `TypedAtmosphere::sample(real_seconds)` принимает секунды от начала повторяющегося расписания. Дорожки идут в порядке файла и занимают свои реальные длительности; после последней дорожки время возвращается к началу. Внутри выбранной дорожки игровой день всегда проходит от 00:00 до 24:00: ```text track_seconds = real_seconds_in_track day_seconds = track_seconds / track_duration * 86400 ``` Время ключа вычисляется по часам и минутам даты. Нативный конструктор игнорирует сохранённое поле секунд, поэтому для планировщика используется: ```text duration = (end_hour * 60 + end_minute) * 60 key_time = floor(duration * (key_hour * 60 + key_minute) * 60 / 86400) ``` Сэмплер ищет предыдущий и следующий ключ во всём расписании. Переход через конец дорожки или конец цикла интерполируется так же, как переход внутри дорожки. `SkeDate::seconds_of_day()` сохраняет все три компонента даты для инструментов; оно не меняет формулу реального времени расписания. День и ночь в самом формате не являются отдельным флагом. Их вид получается из интерполированных цветовых параметров купола и состояния объектов солнца и луны. Ключи с kind `0` и `1` запускают и останавливают небесное светило. Для активного интервала модуль восстанавливает рождение объекта: ищет ближайший предыдущий ключ `SunStart`, следующий соответствующий `SunStop`, вычисляет реальное время начала и длительность, включая переход через цикл, и сохраняет эти значения в `SunBirth`. Имя в первой фиксированной строке определяет объект. Для строки `sun` нативный код использует углы `[90, 30]` градусов и строку материала 3; для `moon` — `[0, 50]` и строку 4. Начальный вектор орбиты строится по формуле `[cos(theta), 0, -sin(theta)]`, где ```text theta = (clamp((now - birth_start) / lifetime, 0, 1) * 1.2 - 0.1) * pi ``` Затем к нему применяется матрица рождения. У солнца и луны независимые интервалы и независимые направления: при отсутствии активной луны нельзя подменять её направление противоположностью солнца. `SunFrame::color` — это единственный primary directional RGB. Второй источник получает направление `-SunFrame::direction` и RGB из `SunSample::packed[1]`; оба источника для активного объекта находятся в `SkyFrame::directional_lights` (сначала солнце, затем луна). Экранная геометрия использует `-SunFrame::direction`, а `world_center` размещает её по нативной формуле относительно camera translation и половины far plane. Материал, строка и состояние объекта берутся из его `SunBirth` и таблицы `sky.wea`. ## Купол Оригинальный `CSky` строит конечный купол, а не кубическую skybox. Значения конструктора, подтверждённые в Terrain, такие: высота `10000`, `theta_max = pi / 4`, вертикальный масштаб `1`, `16` азимутальных секторов и `5` колец. Радиус вычисляется как ```text radius = height * 0.5 / sin(theta_max * 0.5)^2 ``` Вершина с индексом 0 находится в зените `[0, 0, height * z_scale]`. Остальные вершины идут в порядке `azimuth`, затем `ring`; для них ```text phi = azimuth / azimuth_count * 2*pi theta = (ring + 1) / rings * theta_max x = radius * sin(theta) * sin(phi) y = radius * sin(theta) * cos(phi) z = (radius * cos(theta) + height - radius) * z_scale ``` На сектор приходится один треугольник веера и по два треугольника на каждую пару соседних колец. Текстурные координаты трёх исходных стадий используют масштабы `[1, 15, 3]` для `position.x / radius` и `position.y / radius`. Цвет зенита и первого пояса берётся из palette 12. Следующие пояса используют группы palette 8..11, 4..7 и 0..3 с интерполяцией по азимуту. Позиции, signed normal bytes, UV и индексы создаются один раз через `SkyGeometryConfig::mesh`/`SkySystem::new`. Последующие кадры меняют только цвета вершин методом `SkyMesh::update_colors`; индексы и topology не пересоздаются. Ошибка конфигурации возвращается как `SkyGeometryError`, а ошибка входного кадра — как `SkyUpdateError`; они не превращаются в пустой буфер. Рендерер может загрузить `SkySystem::mesh()` в статический vertex/index buffer и обновлять только небольшой цветовой диапазон. Нормали купола повторяют native `Terrain47BFF` contract: каждый компонент хранится как signed `i8`, округляется режимом nearest-even и умножается на `127.0`. `SkyVertex::normal_vector()` декодирует эти bytes делением на `127`; зенит имеет `[0, 0, 127]`. Вершинный backend должен передавать signed byte representation без трактовки его как unsigned `0..255`. ## Облака, звёзды и спрайты `sky.wea` — позиционная таблица. В стандартном AutoDemo строки имеют роли: | Строка | Роль | Имя в AutoDemo | |---:|---|---| | 0 | фон/туманность | `ENV_NEBULA_0` | | 1 | звёзды | `ENV_STARS` | | 2 | облака | `ENV_CLOUDS` | | 3 | солнце | `ENV_SUN_3` | | 4 | луна | `ENV_MOON` | | 5 | первый flare | `ENV_FLARE_00` | | 6 | второй flare | `ENV_FLARE_01` | | 7 | снежинка | `SNOWFLAKE` | | 8 | капля дождя | `RAIN_DROP` | Это наблюдаемые строки, а не глобальные имена, на которые можно полагаться в миссии. `SkyMaterials::parse` сохраняет числовой id и имя каждой строки; миссия может заменить любой материал. `SkyLayerKind` и `SkyLayerFrame` дают роль, позиционную строку, активность, intensity, UV stage и фазу времени. Нативный порядок купола находится в `SkyFrame::passes`: экранный gradient, nebula row 0 со stars row 1 как второй texture (material mode 4), dome gradient и clouds row 2. Для nebula/stars/clouds используются UV scales `1/15/3`; clouds получают translation Z `-5000` относительно камеры и directional RGB из `sky.packed[0]`. Это четыре фиксированных pass, а не три независимых цветных слоя. Цвет первого screen-gradient и последнего пояса вычисляет `SkyFrame::screen_gradient(yaw_radians, glare_rgb_delta)`. Native `CSky` сначала округляет `(yaw + pi) * 180 / pi` режимом nearest-even, выбирает сектор `(floor(degrees / 90) - 2) mod 4`, а затем смешивает соседние цвета `SkySample::colors[0..4]`. Остаток сектора умножается на точный коэффициент из PE `65F64` (`0x3C360B61`, примерно `0.01113567`), alpha результата равна `255`. `glare_rgb_delta` — входной RGB delta от light manager: для каждого канала это `max(current_primary_light_rgb - base_sun_rgb, 0)`. Каждый компонент затем преобразуется так: `d <= 1 -> d*0.8`, `1 < d <= 3 -> d*0.1 + 0.7`, `d > 3 -> 1`. `SkyGradientFrame::horizon_floor` задаёт RGB minimum для dome palette, а `clamp_dome_color` применяет его, сохраняя alpha исходного цвета. Солнце, луна и две строки flare являются направленными экранными слоями. Нативный quad использует UV `[[.005,.005],[.005,.995],[.995,.995],[.995,.005]]`. Полуразмеры sun/moon в пикселях вычисляет `sprite_half_size_pixels`: `viewport_width / horizontal_fov * .325 * .5 * values[0/1]`, где `values` — первые два tail float SKE. Цвет sprite и его alpha берутся из `SunSample::packed[0]`, отдельно от directional `SunFrame::color`. `SkyFrame::sun_optics` принимает projected sun, viewport, camera forward и результат world-ray visibility. Он применяет native 15-degree glare cone и возвращает фиксированные 12 `FlareQuad`; flare slots активны только при видимом солнце, `length(primary RGB) > 1.1` и cone amount `<= .1`. При cone `> .1` остаётся только glare boost. Renderer отвечает за сам projection и occlusion query. Дождь, снег и молния используют те же состояния расписания, но их camera-local геометрия и звуки обновляются `EnvironmentSystem`. Для активного интервала ресурсы берутся только из ключа, который его запустил. Интенсивность дождя, снега и молнии — четвёртый trailing float; цвет активной погоды использует RGB palette 12 с минимумом `80/255` на канал и alpha `150/255`. ## Туман и свет Нативное обновление `CSky` записывает две дальности и один packed RGB. `FogFrame` повторяет этот контракт: ```text fog.start = sky.values[0] * 700 fog.end = sky.values[1] * 700 fog.color = RGB(sky.packed[1]) / 255 ``` Поля не скрывают порядок исходных параметров: значения сохраняются в `SkySample`, а преобразование выполняется только в `fog_frame`. Vulkan path передаёт цвет и дальности в frame uniforms; vertex shader вычисляет линейный коэффициент по расстоянию до камеры, а fragment shader смешивает RGB материала с fog color в ветвях combiner, которые используют туман. Конкретный draw state может обходить это смешивание. Цвет primary света солнца — RGB palette 12, нормированный делением на 255 и умноженный на trailing parameter 2. `SunFrame::direction` — нормированный вектор после матрицы рождения и направление primary light; sprite/world geometry использует его противоположность. Второй directional RGB берётся из packed-параметра 1 без дополнительного умножения intensity. Когда объект неактивен, sampled поля сохраняются, но оба light slot и sprite inactive. В native `CShade` sampled RGB из состояния атмосферы также устанавливает глобальную нижнюю границу освещения. Для каждого RGB-канала она объединяется операцией `max` с накопленным цветом материала. Поэтому `SkyFrame` отдаёт `lighting_floor` из того же sampled packed RGB, а владелец renderer передаёт его в глобальный light state. Фиксированный ambient-цвет в этом месте меняет ночной уровень и не соответствует цепочке Terrain → CShade → Ngi32. ## Бинарный формат `sky.ske` Файл little-endian, версия 5. В начале находятся `i32 marker = -1`, `u32 version = 5` и число дорожек. Дорожка содержит `u32 version = 1`, число ключей, две даты по 32 байта и ключи. Дата состоит из восьми `u32`; для планировщика значимы слова 3, 4 и 5 (часы, минуты, секунды), а остальные слова сохраняются без интерпретации. Ключ имеет `u32 version = 3`, дату, raw kind, opaque word, четыре packed ARGB цвета, два `f32`, пятнадцать packed ARGB цветов, шесть length-prefixed строк, четыре trailing `f32` и список length-prefixed ссылок. Строка хранится как `u32 byte_length` и ровно столько байт без завершающего NUL. Неизвестный kind сохраняется как `AtmosphereKind::Unknown`, как и opaque слова/строки. В конце находятся дата и два opaque `u32`. Декодер ограничивает количества и размеры строк, отклоняет NaN/Infinity во float-полях и требует точного конца файла. Трейлер выбирает исходную дорожку и позицию час/минута; метод `initial_offset_seconds()` складывает длительности предыдущих дорожек и применяет ту же формулу floor. Из интерполированного ключа `SkySample` формируется в исходном порядке: ```text colors = [header[1], header[2], header[0], header[3], palette[0], palette[3], palette[1], palette[2], palette[4], palette[7], palette[5], palette[6], palette[8]] values = header_values packed = [palette[11], palette[13]] ``` Солнце и луна используют palette 12 и trailing parameter 2 для RGB, parameters 0 и 1 сохраняются как raw values, а packed-параметры светила — palette 10 и 14. Kind `0/1` управляет солнцем и луной по имени, `3/4` — дождём, `5/6` — снегом, `8/9` — молнией; kind `2` и `7` меняют интерполируемое состояние. Поля, для которых в native renderer ещё нет проверенного назначения, остаются raw в Rust API и не получают придуманных значений по умолчанию.