norns 脚本参考

此脚本参考是完整 norns API 的补充。在这里，您将找到探索 API 单个组件的示例，这些示例可以复制/粘贴到您自己的脚本中并根据您的需求进行修改。这些示例假设您熟悉 norns 学习 中涵盖的脚本编写概念。

要访问完整的 norns API，您可以：

• 连接到 maiden 并在浏览器中导航到 norns.local/doc
• 访问 静态 API

模块

下面的链接模块名称指向扩展参考示例，这些示例说明了如何在不同上下文中使用命令。(api) 链接指向静态 API。

文件夹结构

脚本位于 ~/dust/code/ 中，是让 norns 执行操作的内容。脚本至少包含一个 Lua 文件，但还可以包含支持 Lua 库、SuperCollider 引擎和数据。

myscript/
  myscript.lua -- 主版本，显示为 MYSCRIPT
  mod.lua -- 替代版本，显示为 MYSCRIPT/MOD
  README.md -- 主文档/说明
  data/
    myscript-01.pset -- pset，通过 params:read(1) 或菜单加载
  lib/
    somelib.lua -- 任意库，通过 require 'lib/somelib' 导入
    some-engine.sc -- 引擎文件
    some-engine.lua -- 引擎库，require lib/some-engine'
  docs/ -- 更多文档
    more-docs.md
  test/ -- 可选的测试脚本
    test-somelib.lua
    test-some-engine.lua

通常，任何 Lua 脚本都会出现在 norns 的 SELECT 菜单中。但名为 crow、data、docs、lib 或 test 的文件夹中的 Lua 脚本将从该菜单中隐藏。

基本脚本

-- scriptname: 简短脚本描述
-- v1.0.0 @author
-- llllllll.co/t/22222

engine.name = 'PolySub'

function init()
  -- 初始化
end

function key(n,z)
  -- 按键操作：n = 数字，z = 状态
end

function enc(n,d)
  -- 编码器操作：n = 数字，d = 增量
end

function redraw()
  -- 屏幕重绘
end

function cleanup()
  -- 反初始化
end

设置最低要求版本

每次 norns 更新都会带来新功能，包括脚本编写和一般可用性。如果您分享的脚本依赖于特定 norns 更新的功能，您可以指定最低版本要求，如果脚本在软件的前一版本上加载，将在 norns 屏幕上显示消息。

要指定最低要求版本，请在脚本的 init() 之前将 norns.version.required 设置为 YYMMDD 值，例如：

-- 最低要求版本检查

norns.version.required = 221214 -- 可以是数字或字符串，格式为 YYMMDD

function init()
  print('hello, welcome to the script')  
end

如果此脚本在运行早于 221214 软件的 norns 上加载，您将在 norns 屏幕上看到：

error: version 221214 required
try 'SYSTEM > UPDATE'

这将在 maiden 中打印：

### SCRIPT ERROR: version 221214 required
### try 'SYSTEM > UPDATE'
### or check for new disk image

有用的系统命令和变量

有一些命令和变量对常见的脚本编写任务很有用。请注意，虽然这些表格可能包含额外的命令和变量，但本节中未提及的任何内容对标准脚本编写都没有用。

这些以分号开头的命令是从 maiden 直接运行的快捷方式：

norns 表包含有用的系统命令和变量：

norns.script 表包含用于脚本生命周期管理的函数：

norns.state 表包含有用的状态数据：

_path 表包含常用文件路径的有用别名：

库

Lua 库可以通过使用 include("path/to/library") 来使用。记住不要在库名称中包含 .lua。

本地库

include() 将首先在当前脚本的目录中查找。这允许使用相对路径来使用脚本本地的库。例如，使用以下结构：

myscript/
  myscript.lua
  lib/
    somelib.lua

myscript.lua 可以使用以下方式包含 somelib.lua：

include("lib/somelib")

第三方库

第三方库可以使用从 ~/dust/code/ 目录开始的完整路径来包含。例如，在 ~/dust/code/ 中使用以下结构：

myscript/
  myscript.lua
  lib/
    somelib.lua
otherscript/
  otherscript.lua
  lib/
    otherlib.lua

myscript.lua 可以使用以下方式包含 otherlib.lua：

include("otherscript/lib/otherlib")

引擎

在脚本顶部指定引擎。有关更多详细信息，请参见 引擎文档。

engine.name = 'PolySub'

如果您想使用来自另一个项目的引擎，请确保首先安装该项目。 如果引擎带有配套的 Lua 文件，请确保导入它：

engine.name = 'R'

local R = require 'r/lib/r'

• engine.list_commands() 显示命令。

例如，将命令 cutoff 设置为 500：

engine.cutoff(500)

要查看所有本地安装引擎的列表：

tab.print(engine.names)

屏幕

屏幕 API 处理在 norns 屏幕上的绘制。有关更多详细信息，请参见 屏幕文档。

function redraw()
  screen.clear()
  screen.move(10,10)
  screen.text("hello world")
  screen.update()
end

metro

metro API 允许高分辨率调度。有关更多详细信息，请参见 metro 文档。

re = metro.init()
re.time = 1.0 / 15
re.event = function()
  redraw()
end

• re:start()，启动 metro。
• re:stop()，停止 metro。

paramset

paramset API 允许读取和写入临时数据和文件。有关更多详细信息，请参见 paramset 文档。

可以使用以下方式安装参数：

params:add{
  type = "number",
  id = "someparam",
  name = "Some Param",
  min = 1,
  max = 48,
  default = 4,
}

• params:set(index, value)，写入参数。
• params:get(index)，读取参数。

系统全局变量

不要覆盖这些变量。这样做可能会破坏事物。

系统全局变量：

_G, _VERSION, assert, bit32, collectgarbage, dofile , error, getmetatable, ipairs, io, load,
loadfile, next, math, os, pairs, pcall, print, rawequal, rawget, rawlen, rawset, require,
select, setmetatable, tonumber, tostring, table, type, utf8, xpcall

norns 全局变量：

_menu, _norns, _path, _startup, arc, audio, cleanup, clock, controlspec, coroutine, crow,
debug, enc, engine, grid, hid, include, inf, key, metro, midi, mix, norns, osc, package,
params, paramset, paths, poll, redraw, screen, softcut, string, tab, util, wifi

设备

grid

grid.connect(n) 创建设备，返回带有处理程序的对象。有关更多详细信息，请参见 grid 文档。

g = grid.connect()

• g:led(x, y, val)，设置此网格设备上单个 LED 的状态。
• g:all(val)，设置此网格设备上所有 LED 的状态。
• g:refresh()，更新此网格设备上的任何脏四边形。
• g.key(x, y, state)，按键事件处理函数。

arc

arc.connect(n) 创建设备，返回带有处理程序的对象。有关更多详细信息，请参见 arc 文档。

a = arc.connect()

• a:led(ring, x, val)，设置此 arc 设备上单个 LED 的状态。
• a:all(val)，设置此 arc 设备上所有 LED 的状态。
• a:segment(ring, from, to, level)，在特定 LED 环上创建抗锯齿的点到点弧 - 段/范围。
• a:refresh()，更新此 arc 设备上的任何脏四边形。
• a.delta(n, delta)，编码器事件处理函数。

midi

midi.connect(n) 创建设备，返回带有处理程序的对象。有关更多详细信息，请参见 midi 文档。

m = midi.connect()

• m:note_on(value,velocity,channel)，发送 note_on 消息。
• m:note_off(value,velocity,channel)，发送 note_off 消息。
• m.event，midi 事件处理函数。

hid

hid.connect(n) 创建设备，返回带有处理程序的对象。有关更多详细信息，请参见 hid 文档。

h = hid.connect()

osc

通过 Open Sound Control 发送网络数据。有关更多详细信息，请参见 osc 文档。

• osc.send(to, path, args)，发送 osc 事件。
• osc.event(path, args, from) 当接收到 osc 事件时调用的处理函数。

crone

pdf 版本

贡献

欢迎对脚本参考的贡献，我们非常感谢任何帮助涵盖这些主题的协助。

对如何贡献有疑问？请随时发送电子邮件至 help@monome.org，我们可以合作！

非常感谢 @fardles (网站) 为 er、fileselect、musicutil、textentry 和 ui 构建参考页面。