API окружения

editorAPI.sky управляет небом и освещением Minecraft в редакторе. Все методы синхронные. Изменяющие методы и refresh() возвращают объект состояния, getMoonPhases() возвращает массив строк. Если подсистема ещё не создана, методы возвращают null, а getMoonPhases() - пустой массив. Вызывайте их после готовности интерфейса, как описано в порядке запуска плагина.

Включение и обновление

editorAPI.sky.enable({ time: 6000, render: true });
editorAPI.sky.disable({ render: true });
editorAPI.sky.refresh({ render: true });

Все объекты параметров необязательны. enable() включает окружение; необязательный time задаёт полное время в тиках до включения. disable() снимает запрос публичного API на показ неба. Методы настройки сами по себе окружение не включают.

render по умолчанию равен true. Только явный false отключает немедленную перерисовку. Это удобно при нескольких настройках подряд:

editorAPI.sky.setDayTime(18000, { render: false });
editorAPI.sky.setMoonPhase('full_moon', { render: false });
editorAPI.sky.setGamma(0.5, { render: false });
editorAPI.sky.enable();

refresh() пересчитывает визуальное состояние по текущему времени и при необходимости перерисовывает сцену. Его не нужно вызывать после каждого setter с обычными параметрами.

Время суток

Метод	Поведение
setTime(ticks, options = {})	Установить полное время. Число дней влияет на фазу Луны.
setDayTime(ticks, options = {})	Изменить время внутри текущего дня, сохранив номер дня.
tick(delta = 1, options = {})	Прибавить delta к полному времени. Отрицательное значение переводит время назад.

Один день составляет 24 000 игровых тиков. При обычной скорости Minecraft 20 тиков соответствуют секунде, но эти методы не запускают таймер и не привязываются к реальному времени. Каждый вызов tick() делает только один шаг.

Числа преобразуются через Number(). Конечные отрицательные и дробные значения допустимы; NaN и бесконечности оставляют состояние прежним. В setDayTime() значение приводится по модулю 24 000: 24000 даст начало текущего дня, -1 - 23999. Полное время setTime() не ограничивается одним днём.

Время внутри дня	Ориентир
0	Начало дня.
6000	Полдень.
12000	Вечер.
18000	Полночь.

Начальное полное время при создании подсистемы - 6000. Фактическое текущее значение читайте через getState(), поскольку окружением могут управлять другие режимы редактора.

Фаза Луны

editorAPI.sky.setMoonPhase(4);
editorAPI.sky.setMoonPhase('new_moon');
const phases = editorAPI.sky.getMoonPhases();

Индекс	Идентификатор	Фаза
0	full_moon	Полнолуние.
1	waning_gibbous	Убывающая выпуклая Луна.
2	third_quarter	Последняя четверть.
3	waning_crescent	Убывающий серп.
4	new_moon	Новолуние.
5	waxing_crescent	Растущий серп.
6	first_quarter	Первая четверть.
7	waxing_gibbous	Растущая выпуклая Луна.

setMoonPhase(phase, options = {}) принимает числовой индекс или точный строковый идентификатор. Числовое значение округляется и приводится по модулю восьми: 8 означает 0, -1 означает 7. Неизвестная строка оставляет состояние прежним.

Метод меняет номер дня в текущем восьмидневном цикле, сохраняя время суток. Поэтому меняется и totalTicks. Последующий setTime() снова определит фазу по полному времени. getMoonPhases() возвращает копию массива идентификаторов в порядке индексов.

Гамма окружения

editorAPI.sky.setGamma(value, options = {});

Значение преобразуется через Number() и ограничивается диапазоном 0-1. Начальное значение - 0.5. Нечисловое значение или бесконечность не меняют состояние.

Это параметр игрового освещения MinecraftSky. Он не является настройкой гаммы итогового изображения Render RT. Метод обновляет освещение и, если render не равен false, перерисовывает сцену.

Дальность окружения

editorAPI.sky.setRenderDistance(chunks, options = {});

chunks измеряется в чанках по 16 блоков. Значение преобразуется в число и ограничивается диапазоном 2-250 без округления до целого. Начальное значение - 25.

Параметр влияет на отображение окружения и мировой туман. Дальняя граница этого тумана равна min(chunks * 16, 512) блокам, ближняя - 75% дальней. Поэтому после 32 чанков дальняя граница тумана уже не отодвигается. Это не команда загрузки чанков и не настройка радиуса Minecraft Live Link.

Состояние и совместимость

const state = editorAPI.sky.getState();

Поле	Значение
active	Включено ли окружение хотя бы одним владельцем.
owners	Массив строковых владельцев включения. Публичный API использует editor-api.
totalTicks	Полное время в игровых тиках.
dayTime	Время внутри дня, от 0 включительно до 24 000 исключительно.
sunAngle	Вычисленный угол Солнца в градусах.
moonPhase, moonPhaseName	Индекс и строковый идентификатор фазы.
starBrightness	Вычисленная яркость звёзд в текущем состоянии неба.
gamma	Гамма игрового освещения, 0-1.
renderDistanceChunks	Настроенная дальность в чанках.

Это снимок значений. Изменение возвращённого объекта не изменяет окружение. В sky также существует getSky(), возвращающий внутренний MinecraftSky или null; его поля и дополнительные методы относятся к внутреннему устройству редактора и могут меняться.

Включение имеет несколько владельцев. Погружение, Live Link и анимация времени суток могут держать окружение включённым независимо от плагина. Поэтому после disable() поле active может остаться true. Все плагины через editorAPI.sky используют одного владельца editor-api: вызов disable() одного плагина снимает общий запрос API, а не только его собственный.

Окружение общее и по значениям: Live Link может обновлять время из мира, а Animator - из трека времени суток. setTime() не создаёт ключ анимации, не записывает команду Undo и не сохраняет настройку плагина в проект. Текущие значения sky отдельно в .bdengine не сериализуются; для повторяемого пресета храните необходимые значения в настройках своего плагина и применяйте их явно. Анимационные ключи времени суток и сохранение проекта - отдельные механизмы редактора.

Практический пример управления параметрами и завершения работы: «Управлять окружением».

Применить на практике

Управлять окружениемСделать панель управления подтверждёнными параметрами окружения.