-*- mode: org; mode: visual-line; -*-

The shado grid and arc rendering library in Lua for the monome norns.

shado is a compositing and sprite library for grid and arc devices attached to the monome norns. It is based on an earlier release written in Java as an OSC subsystem; this version is written in Lua to run on norns natively.

To get a sense for what’s achievable in shado (as of 13 years ago with first-generation monome kit), take a look at this video.

The file README.MANUAL will eventually be the manual for shado; for now, it contains an explanation of the shado architecture - quite possibly, along with the API docs and the examples, just about enough to start writing shado “programs”.

On norns, download this repository into /home/we/dust/code (at least until we get a proper package built) - it must have the name shado. If you download and unpack the ZIP file the folder will be named something like `shado-main`, so rename it.

Maiden can also download and install the package directly, via:

;install https://github.com/cassiel/shado

Once that’s done, from the norms screen, load the shado script. Don’t try to load any of the other files - they’re an assortment of tests and support scripts. The main shado script is a container for a number of simple and (mostly) interactive demo applications (living in the apps directory). The on-screen instructions will introduce the individual demos, and the buttons will scroll between them.

Install luarocks (the Lua package manager) and luaunit (the unit testing library). On norns:

sudo apt-get install luarocks
sudo luarocks install luaunit

Note: the command-line Lua on norns is currently version 5.1. (You might be able to upgrade it.) The Lua used for scripting is 5.3. The unit tests should work under 5.1, although that version is under-tested.

To set up the tests on macOS (with Homebrew):

brew install luarocks
luarocks install luaunit

We also use the library inspect for some debugging in the tests; install as above.

From the directory containing shado (on the norns that would be /home/we/dust/code), test with:

lua shado/test-all.lua

We’ve used LDoc, which can be cleanly installed with:

[sudo] luarocks install ldoc

From the main shado directory, a ldoc -v . reads from config.ld and generates docs in docs (which is where GitHub Pages wants them).

• All coordinates have origin or top-left at (1, 1) (Lua-style) rather than (0, 0) (every other language in the world-style).
• Rename: ViewPort is now called Mask, which is a bit snappier and more indicative of what it actually does.
• In the Java implementation, press() is a boolean method returning true for press handled, false otherwise. Since Lua is more dynamic, we can have press-handled as the default by omitting any return statement - i.e., a result of nil implies handled. In fact, false is the only return value to mark a press as not handled.