Skydimo 腳本開發完全指南

歡迎來到 Skydimo 腳本開發的世界！無論你是初學者還是進階使用者，本指南都能協助你學習如何使用 Lua 腳本打造專屬的 RGB 燈效。此功能目前於 Skydimo 測試版（beta）中提供。

目錄

---

功能總覽

• 自由創作：用 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)

用途：計算每顆 LED 的顏色值（每個畫面會呼叫多次）

參數：

• 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：自啟動以來累計的時間（秒，浮點數）
• env.dt：上一個畫面到目前畫面的時間間隔（秒）
• env.fps：目前的畫面更新率（每秒畫面數）
• env.random：0–1 的隨機數種子（每個畫面都會變化）
• env.bpm：每分鐘節拍數（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 中執行複雜計算並快取結果
• 避免建立大量暫存表（table）
• 盡可能使用預先計算好的查找表

---

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：取決於主機端的實作方式；建議每個裝置同時啟用一個腳本，以確保偵錯與效能。

---