SuperAPI AI 工具集

disting-nt-lua-scripter

编程与开发

查看项目

更新于 10-16 06:57

技能介绍

用途

该技能面向 Disting NT Eurorack 模块的 Lua 脚本开发,用于在控制分辨率(非音频速率)下处理 CV 信号、门限(gate)与触发(trigger)。脚本的 step 函数以 1000Hz 执行,gate 与 trigger 函数响应输入事件,draw 函数以 30fps 渲染。

主要能力

  • 以 1000Hz 的 step 回调处理输入并返回输出电压。
  • 通过 trigger、gate 回调响应输入事件。
  • 通过 draw 回调以 30fps 绘制自定义 UI。
  • 支持 serialise 状态序列化与 midiMessage MIDI 消息处理。
  • 当前硬件提供 64 条逻辑总线:12 条输入、8 条输出、44 条辅助总线;允许脚本声明最多 64 个输入/输出并使用总线索引 0-63。
  • 注意:v1.17 Lua 手册中较旧的 0-28 表述已过时,应以 v1.17 用户手册的信号流架构为当前依据。

使用方式

所有脚本必须返回一个表,包含:

  • name 与 author 字段
  • init(self) 函数,返回配置
  • step(self, dt, inputs) 函数,返回输出电压

可选回调:trigger、gate、draw、ui、serialise、midiMessage。

关键回调签名区别:

  • Lua Script 算法与自定义算法 UI 回调首先接收 self。
  • 独立 UI 脚本使用不带 self 的回调;其 init() 成功时返回 true,失败时返回错误字符串,事件处理器只接收文档化的事件值。

快速开始示例(基本 LFO 脚本,生成方波与三角波):

return {
    name = 'LFO',
    author = 'Expert Sleepers Ltd',

init = function(self)
    self.t = 0.0
    return {
        inputs = 1,
        outputs = { kStepped, kLinear }
    }
end,

step = function(self, dt, inputs)
    local f = 1 + inputs[1]
    self.t = (self.t + dt * f) % 1.0
    local sqr = self.t > 0.5 and 5.0 or -5.0
    local tri = 20 * math.min(self.t, 1 - self.t) - 5
    return { sqr, tri }
end

}

step 函数以 1000Hz 运行。输入 1 调制频率。输出 1 为方波(stepped),输出 2 为三角波(linear 插值)。

参考指南:

  • 完整 API 参考:reference.md —— 固件 v1.17 回调、参数、绘图 API、发现、MIDI/I2C、序列化与兼容性检查
  • 可用示例:examples.md —— LFO、ADSR、移位寄存器与弹跳球实现
  • 算法模板:templates/template.lua —— 带注释的 Lua Script 算法模板
  • 独立 UI 模板:templates/ui-script.lua —— 正确的不带 self 的 UI 脚本签名

适用场景

适用于为 Disting NT Eurorack 模块编写 Lua 脚本,处理 CV 信号、门限与触发,或实现自定义 UI、MIDI 消息处理与状态序列化等场景。

限制

脚本运行在控制分辨率而非音频速率。成功标准包括:

  • 加载时无 Lua 语法错误
  • 通过 step/trigger/gate 回调以 1000Hz 处理输入
  • 返回正确的电压范围(通常为 -10V 至 +10V)
  • 若实现 draw(),以 30fps 绘制自定义 UI
  • 若实现 serialise(),正确序列化状态
  • 使用预分配表以避免 step() 期间的垃圾回收
  • 若实现 midiMessage(),正确处理 MIDI 消息
  • 返回稀疏输出表时保留未更改的输出
  • 整数绘图原语使用整数坐标,仅 drawSmoothLine/drawSmoothCircle 使用浮点坐标
  • 算法脚本与独立 UI 脚本使用正确的回调签名