Полное руководство по разработке скриптов Skydimo

Добро пожаловать в мир разработки скриптов Skydimo! Это руководство поможет вам научиться создавать собственные эффекты RGB-подсветки с использованием скриптов Lua, независимо от того, новичок вы или опытный пользователь. Эта функция доступна в бета-версии Skydimo.

Содержание

---

Обзор функций

• Творческая свобода: Создавайте уникальные световые эффекты с помощью кода Lua
• Помощь AI: Генерируйте пользовательские эффекты одним предложением, AI помогает писать и оптимизировать код
• Реакция на звук: Заставьте свет танцевать под музыку, поддержка анализа спектра FFT в реальном времени
• Управление вкладками: Редактируйте несколько скриптов одновременно, легкое переключение и организация
• Горячая перезагрузка: Изменения вступают в силу немедленно, не требуется перезапуск программы
• Импорт/Экспорт: Делитесь своими творениями или используйте скрипты сообщества
• Полный контроль: Скорость, яркость, цветовая температура и оттенок под вашим контролем

---

Быстрый старт

Ваш первый скрипт: Радужный градиент

В Skydimo → страница “Скрипты”, создайте новый скрипт и введите:

function get_color(x, y, width, height, env)
    -- Генерация радужных цветов на основе позиции и времени
    local hue = (x / width * 360 + env.time * 60) % 360
    return hsv(hue, 255, 255)
end

Шаги:

1. Нажмите кнопку “Режим регистрации” в правом верхнем углу
2. Найдите только что зарегистрированный скрипт в списке режимов
3. Нажмите для активации, устройство отобразит плавный радужный градиент

Объяснение кода:

• get_color: Функция, вызываемая для каждого пикселя
• x / width: Генерация соотношения позиции 0–1
• env.time: Постоянно растущее значение времени, заставляет цвета течь
• hsv(): Преобразование оттенка, насыщенности, яркости в цвет RGB

---

Основы Lua

Что такое Lua?

Lua — это легкий, простой в изучении язык программирования. Skydimo использует Lua 5.4.

Краткий справочник по синтаксису

-- Однострочный комментарий

--[[
  Многострочный комментарий
  Можно писать несколько строк
]]

-- Определение переменных (объявление типа не требуется)
local speed = 100
local name = "Rainbow"
local enabled = true

-- Математические операции
local result = (10 + 5) * 2 / 3

-- Условные операторы
if x > 10 then
    -- Выполнить код
elseif x == 5 then
    -- Другой случай
else
    -- Случай по умолчанию
end

-- Циклы
for i = 1, 10 do
    -- Повторить 10 раз
end

-- Определение функции
local function calculate(a, b)
    return a + b
end

---

Спецификация API

Обязательная функция: get_color(x, y, width, height, env)

Назначение: Вычислить значение цвета для каждого светодиода (вызывается несколько раз за кадр)

Параметры:

• x, y: Координаты текущего пикселя (начиная с 0)
• width, height: Общая ширина/высота устройства
• env: Объект переменных окружения

Возвращаемое значение: 32-битное целое число, формат 0x00BBGGRR (порядок Синий-Зеленый-Красный, каждый канал 0–255)

Пример:

function get_color(x, y, width, height, env)
    return rgb(255, 0, 0)  -- Чистый красный
end

Опциональная функция: begin_frame(env)

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

-- Глобальная переменная хранит предварительно вычисленные результаты
local wave_offset = 0

function begin_frame(env)
    -- Вычислить смещение волны один раз за кадр
    wave_offset = math.sin(env.time) * 50
end

function get_color(x, y, width, height, env)
    -- Использовать предварительно вычисленное значение напрямую
    local hue = (x / width * 360 + wave_offset) % 360
    return hsv(hue, 255, 255)
end

---

Переменные окружения

Общие поля в объекте окружения env:

• env.time: Накопленное время с момента запуска (секунды, float)
• env.dt: Временной шаг от предыдущего кадра к текущему (секунды)
• env.fps: Текущая частота кадров (кадров/секунду)
• env.random: Случайное число 0–1 (изменяется каждый кадр)
• env.bpm: Ударов в минуту, для эффектов, управляемых ритмом (опционально)
• env.audio: Объект аудиоданных (опционально)
  • env.audio.level: Общая громкость 0–1
  • env.audio.fft: Массив спектра, от низкой к высокой частоте
  • env.audio.sampleRate: Частота дискретизации аудио
  • env.audio.enabled: Включен ли аудиовход

---

Встроенная библиотека функций

Конструирование и преобразование цвета:

• rgb(r, g, b): Возврат 32-битного цвета
• hsv(h, s, v): HSV в RGB, h: 0–360, s/v: 0–255
• saturate(v): Ограничить значение до 0–1
• clamp(v, min, max): Обрезка диапазона
• mix(a, b, t) / lerp(a, b, t): Линейное смешивание
• smoothstep(edge0, edge1, x): Плавный шаг
• map(x, inMin, inMax, outMin, outMax): Отображение диапазона

Шум и случайность:

• random(): Случайное 0–1
• noise1(x) / noise2(x, y): Плавный шум

---

Визуализация аудио

Пример визуализации спектра:

local spectrum = {}

function begin_frame(env)
    if env.audio and env.audio.fft then
        spectrum = env.audio.fft
    end
end

function get_color(x, y, width, height, env)
    if not spectrum or #spectrum == 0 then
        return rgb(10, 10, 10)
    end
    local band = math.max(1, math.floor((x / width) * #spectrum))
    local amp = spectrum[band] or 0
    local h = (band / #spectrum) * 360
    local v = math.floor(math.min(255, amp * 255 * 1.5))
    return hsv(h, 255, v)
end

---

Механизм выполнения

Последовательность цикла рендеринга:

1. Вызов begin_frame(env) в начале кадра (если реализовано)
2. Затем вызов get_color(x, y, width, height, env) для каждого пикселя
3. Отправка буфера цветов кадра на устройство

Советы по производительности:

• Выполняйте сложные вычисления в begin_frame и кэшируйте результаты
• Избегайте создания множества временных таблиц
• Используйте предварительно вычисленные таблицы поиска, когда это возможно

---

Разработка с помощью AI

Опишите желаемый эффект в редакторе скриптов (например, “низкая частота управляет теплыми цветовыми полосами, импульс ритма усиливает яркость”), и AI сгенерирует начальный код. Продолжайте предлагать модификации для быстрой итерации.

---

Практические примеры

1) Столбчатая диаграмма спектра (горизонтальная)

local smoothed = {}

function begin_frame(env)
    if not (env.audio and env.audio.fft) then return end
    local fft = env.audio.fft
    for i = 1, #fft do
        local v = fft[i]
        smoothed[i] = smoothed[i] and (smoothed[i] * 0.6 + v * 0.4) or v
    end
end

function get_color(x, y, width, height, env)
    if not smoothed or #smoothed == 0 then return rgb(0,0,0) end
    local band = math.max(1, math.floor((x / width) * #smoothed))
    local level = smoothed[band] or 0
    local barH = math.floor(level * height)
    if (height - 1 - y) <= barH then
        local hue = (band / #smoothed) * 360
        return hsv(hue, 255, 255)
    else
        return rgb(0, 0, 0)
    end
end

---

Лучшие практики

• Приоритет тяжелым вычислениям в begin_frame и предварительной обработке данных
• Кэшируйте часто используемые глобальные объекты локальными переменными
• Осторожно создавайте временные таблицы, избегайте накладных расходов на расширение table.insert в циклах
• Защищайте параметры и возвращаемые значения проверками границ
• Поддерживайте согласованные диапазоны цвета и яркости (0–255), обрезайте при превышении

---

FAQ

Q1: Какой формат возврата get_color?
A: Возвращает 32-битное целое число, формат 0x00BBGGRR.

Q2: Почему не реагирует визуализация аудио?
A: Проверьте env.audio.enabled и устройство ввода; также подтвердите, предоставило ли среда выполнения разрешение на микрофон.

Q3: Как улучшить частоту кадров?
A: Уменьшите сложные вычисления в get_color; поместите повторно используемые значения в begin_frame; избегайте создания временных таблиц.

Q4: Поддерживается ли одновременное выполнение нескольких скриптов?
A: Зависит от реализации хоста; рекомендуется активировать один скрипт на устройство для отладки и обеспечения производительности.

---