norns script reference
Scripts are located in ~/dust/code/
, and are what make norns do things. A script consists of at least a Lua file but can additionally also contain supporting Lua libraries, SuperCollider engines and data.
directory structure
myscript/
myscript.lua -- main version, shows up as MYSCRIPT
mod.lua -- alt version, shows up as MYSCRIPT/MOD
README.md -- main docs/readme
data/
myscript-01.pset -- pset, loaded via params:read(1) or via menu
lib/
somelib.lua -- arbitrary lib, imported via require 'lib/somelib'
some-engine.sc -- engine file
some-engine.lua -- engine lib, require lib/some-engine'
docs/ -- more documentation, won't be shown in SELECT
more-docs.md
basic script
-- scriptname: short script description
-- v1.0.0 @author
-- llllllll.co/t/22222
engine.name = 'PolySub'
function init()
-- initialization
end
function key(n,z)
-- key actions: n = number, z = state
end
function enc(n,d)
-- encoder actions: n = number, d = delta
end
function redraw()
-- screen redraw
end
function cleanup()
-- deinitialization
end
libraries
Lua libraries can be used by using include("path/to/library")
, remember not to include .lua
in the library name.
local libraries
include()
will first look in the directory of the current script. This allows using relative paths to use libraries local to the script. For example, with the following structure:
myscript/
myscript.lua
lib/
somelib.lua
myscript.lua
can include somelib.lua
using:
include("lib/somelib")
third-party libraries
Third party libraries can be included using their full path starting from the ~/dust/code/
directory. For example, with the following structure in ~/dust/code/
:
myscript/
myscript.lua
lib/
somelib.lua
otherscript/
otherscript.lua
lib/
otherlib.lua
myscript.lua
can include otherlib.lua
using:
include("otherscript/lib/otherlib")
engine
Specify an engine at the top of your script, see the engine docs for more details.
engine.name = 'PolySub'
If you want to use an engine from another project make sure to install that project first. If the engine comes with an accompanying Lua file make sure to import it:
engine.name = 'R'
local R = require 'r/lib/r'
engine.list_commands()
shows the commands.
For example to set the command cutoff
to 500:
engine.cutoff(500)
To see a list of all locally installed engines:
tab.print(engine.names)
screen
The screen API handles drawing on the norns screen, see the screen docs for more details.
function redraw()
screen.clear()
screen.move(10,10)
screen.text("hello world")
screen.update()
end
metro
The metro API allows for high-resolution scheduling, see the metro docs for more details.
re = metro.init()
re.time = 1.0 / 15
re.event = function()
redraw()
end
re:start()
, starts metro.re:stop()
, stops metro.
paramset
The paramset API allows to read and write temporary data and files, see the paramset docs for more details.
A parameter can be installed with the following:
params:add{type = "number", id = "someparam", name = "Some Param", min = 1, max = 48, default = 4}
params:set(index, value)
, writes a parameter.params:get(index)
, reads a parameter.
devices
grid
grid.connect(n)
to create device, returns object with handler, see the grid docs for more details.
g = grid.connect()
g:led(x, y, val)
, sets state of single LED on this grid device.g:all(val)
, sets state of all LEDs on this grid device.g:refresh()
, update any dirty quads on this grid device.g.key(x, y, state)
, key event handler function.
arc
arc.connect(n)
to create device, returns object with handler, see the arc docs for more details.
a = arc.connect()
a:led(ring, x, val)
, sets state of single LED on this arc device.a:all(val)
, sets state of all LEDs on this arc device.a:segment(ring, from, to, level)
, creates an anti-aliased point to point arc - segment/range on a specific LED ring.a:refresh()
, updates any dirty quads on this arc device.a.delta(n, delta)
, encoder event handler function.
midi
midi.connect(n)
to create device, returns object with handler, see the midi docs for more details.
m = midi.connect()
m:note_on(value,velocity,channel)
, sendsnote_on
message.m:note_off(value,velocity,channel)
, sendsnote_off
message.m.event
, midi event handler function.
hid
hid.connect(n)
to create device, returns object with handler, see the hid docs for more details.
h = hid.connect()
osc
osc.send(to, path, args)
, sends osc event.osc.event(path, args, from)
handler function called when an osc event is received.