Освещение и цветокоррекция

1. Быстрый старт

1. Возьмите готовый полный timecyc.json и сохраните резервную копию.
2. Редактируйте JSON вручную либо откройте его в дополнительном редакторе. Он работает локально, без сервера и отправки файла в сеть.
3. Выберите погодный профиль по name. Параметры света находятся в lighting, цветокоррекции — в grading.
4. Сохраните полный файл под именем timecyc.json в папку data каталога хранения игры.
5. Перезапустите клиент, чтобы он перечитал настройки. Для изменения только JSON пересборка библиотеки не нужна.

Точный путь загрузки: GAME_STORAGE_PATH + "data/timecyc.json". В GAME_STORAGE_PATH уже должен быть завершающий разделитель; загрузчик не исправляет путь и не ищет файл в других папках.

2. Загрузка и обработка ошибок

Файл читается при инициализации timecycle, а не каждый кадр. Замена файла во время игры сама по себе не обновляет картинку; обычный способ применения — перезапуск клиента.

• Используется один JSON для освещения и цветокоррекции. Отдельный colorcycle.json не требуется.
• Встроенных настроек и автоматической замены из DAT нет. JSON необходим, чтобы установить timecycle-параметры.
• При отсутствии файла, ошибке чтения или неверных значениях инициализация пропускается без завершения процесса.
• Одна ошибка отклоняет весь документ: правильная половина конфига отдельно не применяется. При неудачной повторной загрузке предыдущие настройки остаются неизменными.

Если настройки не применились

1. Проверьте имя и расположение файла, а также доступность для чтения.
2. Откройте его в редакторе: он проверяет имена, поля, типы, повторы и числовые диапазоны.
3. Проверьте, что файл сохранён целиком, содержит все профили и не превышает 8 МиБ.
4. При необходимости посмотрите Android log: tag DragonMobile, префикс CTimeCycleCustom. Сообщение укажет причину пропуска.

Предпросмотр редактора условный. Корректный файл и ожидаемый визуальный результат нужно проверять в игре, особенно для тумана, дальности, теней и post-FX.

3. Структура единого JSON

Корень содержит только weathers. У профиля — только name, lighting и grading. Имя определяет профиль; поля id в профиле быть не должно.

{
  "weathers": [
    {
      "name": "EXTRASUNNY_LA",
      "lighting": [
        {
          "time": "00:00",
          "ambient": [22, 22, 22],
          "object_ambient": [220, 212, 130],
          "legacy_directional": [255, 255, 255],
          "sky_top": [0, 23, 24],
          "sky_bottom": [0, 31, 32],
          "sun_core": [255, 128, 0],
          "sun_corona": [5, 0, 0],
          "sun_size": 1.0,
          "sprite_size": 1.0,
          "sprite_brightness": 0.3,
          "shadow": 200,
          "light_shadow": 100,
          "pole_shadow": 0,
          "far_clip": 400.0,
          "fog_start": 100.0,
          "ground_brightness": 1.0,
          "low_clouds": [30, 20, 0],
          "fluffy_clouds_bottom": [3, 3, 3],
          "water": [85.0, 85.0, 65.0, 240.0],
          "postfx1": [87.0, 87.0, 87.0, 255.0],
          "postfx2": [60.0, 121.0, 122.0, 255.0],
          "cloud_alpha": 0.0,
          "highlight_min": 90,
          "water_fog_alpha": 0,
          "directional_multiplier": 1.28
        }
      ],
      "grading": [
        {
          "time": "00:00",
          "red": [2.124, 0.0, 0.0, -0.007],
          "green": [0.0, 2.124, 0.0, -0.007],
          "blue": [0.0, 0.0, 2.124, -0.007]
        }
      ]
    }
  ]
}

Это пример одного полного профиля, не самостоятельный runtime-файл: в настоящем конфиге нужны остальные 22 профиля. В примере у обоих разделов одна точка, поэтому их значения постоянны весь день.

Сохраняйте точные имена ключей и профилей: регистр имеет значение. Комментарии, неизвестные поля, повторные ключи и пропущенные обязательные поля запрещены. Не добавляйте schema_version, document_type или metadata.

Все lighting-поля обязательны, кроме directional_multiplier. При его отсутствии используется 1.28 именно для этой точки, без наследования от соседних точек.

4. Погодные профили и пресеты

Профили ниже должны присутствовать по одному разу. Порядок профилей в файле не важен; их имена менять нельзя.

Чем пресет отличается от времени

Во всех профилях, кроме EXTRACOLOURS_1 и EXTRACOLOURS_2, точки выбираются по time. В двух extra-colour банках вместо него используется preset: целое число от 0 до 7.

Каждый из массивов lighting и grading extra-colour профиля должен иметь ровно восемь точек, с каждым preset 0–7 по одному разу. Это не дневные кривые: туда нельзя добавлять время или девятый пресет.

Extra-colour настройки используются игровыми эффектами, областями и скриптами. Например, для туннельного пресета применяется EXTRACOLOURS_2 с локальным preset: 1. Выбор этих эффектов остаётся задачей игры; конфиг меняет их значения.

5. Поля освещения

RGB записывается как [красный, зелёный, синий], RGBA — как [красный, зелёный, синий, alpha]. Числа в конфиге — исходные настройки, не готовые значения после преобразования загрузчиком.

Дробные значения разрешены только там, где указано «число». Для целых каналов 22.0 допустимо, а 22.5 — нет. У воды, post-FX и cloud_alpha дробная часть после преобразования в float32 отбрасывается к нулю; так же обрабатываются расстояния.

S10: trunc(fmaf(float32(value), 10.0, 0.5)) → −128…127
U10: trunc(fmaf(float32(value), 10.0, 0.5)) → 0…255
U100: trunc(float32(float32(value) * 100)) → 0…255

6. Цветокоррекция

Точка grading содержит time либо preset и три массива: red, green, blue. Каждый массив задаёт четыре вклада исходных каналов R, G, B, alpha в один выходной канал.

{
  "time": "06:30",
  "red": [2.124, 0.0, 0.0, -0.007],
  "green": [0.0, 2.124, 0.0, -0.007],
  "blue": [0.0, 0.0, 2.124, -0.007]
}

• Первый коэффициент строки red — вклад исходного R в выходной красный, второй — вклад G, третий — B, четвёртый — alpha. У остальных строк такой же порядок входов.
• Это коэффициенты, не цветовые байты: их не нужно делить на 255.
• Отрицательные значения и усиление больше 1 допустимы; каждый массив должен содержать ровно четыре числа.
• Четвёртый коэффициент умножает alpha исходной текстуры. Он похож на постоянное смещение только для непрозрачного источника; это не поле прозрачности.

Не обрабатывайте коэффициенты вручную

Загрузчик преобразует каждую ключевую точку один раз перед интерполяцией. В JSON нужны исходные коэффициенты. Для каждой строки (x, y, z, w) преобразование имеет вид:

sum = (x + y) + z
correction = sum > 1.7 ? (sum - 1.7) * 0.13 : 0
stored = (x * 0.67, y * 0.67, z * 0.67, (w - correction) * 0.67)

Шаги округляются до float32 отдельно. Слишком большие коэффициенты, переполняющие промежуточные вычисления, отклоняются. Если нужен отрицательный ноль, используйте -0.0: целое -0 интерпретируется игрой как обычный ноль.

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

7. Время и интерполяция

• У каждой обычной погоды, включая UNDERWATER, в каждом разделе может быть от 1 до 1440 различных точек за сутки.
• Формат — ASCII-строка HH:MM, например 06:05. Часы и минуты всегда по две цифры. Диапазон: 00:00…23:59; 24:00 запрещено.
• Порядок точек в файле не важен. Повторы одного времени запрещены внутри одного раздела, но одинаковое время в lighting и grading допустимо.
• Между точками значения интерполируются. Переход от последней точки через полночь к первой точке следующего дня также плавный.
• Полночь не обязательна. Одна точка означает постоянные значения в течение всех суток независимо от её времени.

Поставляемый JSON использует исходные времена 00:00, 05:00, 06:00, 07:00, 12:00, 19:00, 20:00, 22:00. Это исходный набор, а не ограничение: можно добавить любую свободную минуту.

Общий размер файла и проверка его содержимого могут ограничить очень плотную конфигурацию раньше, чем каждая погода получит 1440 точек. Extra-colour банки не используют время и остаются наборами фиксированных пресетов.

8. Примеры редактирования

Добавить рассветное освещение в 06:30

В выбранном профиле скопируйте полную соседнюю lighting-точку. Задайте уникальное time: "06:30", затем меняйте нужные значения. В редакторе кнопка «Добавить точку…» делает такую копию автоматически только в выбранном разделе.

Ниже полная примерная lighting-точка. Вставьте её в lighting нужной погоды, а не вместо всего файла:

{
  "time": "06:30",
  "ambient": [40, 32, 28],
  "object_ambient": [220, 212, 130],
  "legacy_directional": [255, 255, 255],
  "sky_top": [0, 23, 24],
  "sky_bottom": [0, 31, 32],
  "sun_core": [255, 128, 0],
  "sun_corona": [5, 0, 0],
  "sun_size": 1.0,
  "sprite_size": 1.0,
  "sprite_brightness": 0.3,
  "shadow": 200,
  "light_shadow": 100,
  "pole_shadow": 0,
  "far_clip": 650.0,
  "fog_start": 100.0,
  "ground_brightness": 1.0,
  "low_clouds": [30, 20, 0],
  "fluffy_clouds_bottom": [3, 3, 3],
  "water": [85.0, 85.0, 65.0, 240.0],
  "postfx1": [87.0, 87.0, 87.0, 255.0],
  "postfx2": [60.0, 121.0, 122.0, 255.0],
  "cloud_alpha": 0.0,
  "highlight_min": 90,
  "water_fog_alpha": 0,
  "directional_multiplier": 1.28
}

Если в этом разделе уже есть 06:30, измените существующую точку вместо добавления дубликата. Значения примера условные: для настройки своей погоды лучше брать её соседнюю точку.

Задать цветокоррекцию на другое время

Например, свет меняется в 06:30, а оттенок должен начать меняться раньше. Добавьте в grading отдельную точку 06:15, не меняя lighting-расписание:

{
  "time": "06:15",
  "red": [2.2, 0.0, 0.0, -0.007],
  "green": [0.0, 2.1, 0.0, -0.007],
  "blue": [0.0, 0.0, 1.9, -0.007]
}

Это пример усиления красного относительно синего. Реальный оттенок зависит от освещения сцены и обработки коэффициентов; сравните результат в редакторе и затем в игре.

Сделать значения постоянными

У обычного профиля оставьте одну полную точку в нужном разделе, например 23:15. Этот раздел станет постоянным весь день. Другой раздел может сохранить все свои временные точки.

Изменить фиксированный extra-colour пресет

В EXTRACOLOURS_2 найдите существующую grading-точку preset: 1 и замените её значения, например:

{
  "preset": 1,
  "red": [2.124, 0.0, 0.0, -0.007],
  "green": [0.0, 2.124, 0.0, -0.007],
  "blue": [0.0, 0.0, 2.124, -0.007]
}

Не добавляйте этот пример девятой точкой. Lighting-пресет с тем же номером настраивается отдельно, но оба extra-colour раздела должны сохранить весь набор 0–7.