Writing LMS Scripts

LMS Script is a small, friendly language for generating live LED-matrix animations. You write a bit of setup and a bit of per-frame drawing, and LMS runs it straight onto your wall. It's the same format as classic Jinx! scripts (.jns), so scripts from the wider community work too.

Quick start

Every script has two parts: :init (runs once) and :render (runs every frame). Here's a complete script that scatters coloured sparkles:

:init
    # runs ONCE when the effect starts
    w = matrix_x
    h = matrix_y
end

:render
    # runs EVERY frame — draw into the matrix
    clear
    x = rnd(w - 1)
    y = rnd(h - 1)
    pset x, y, autocolor_red, autocolor_green, autocolor_blue
end

Open the Edit script button under the effect's Script dropdown to try it — you get a live preview and instant error checking as you type.

Importing Jinx scripts

LMS Script is Jinx!Script — the same language and the same .jns file format used by the classic Jinx! software. That means the huge library of scripts people have written and shared over the years runs straight in LMS, no conversion needed.

Imported scripts are saved inside your project (the .lmc file), so they travel with it — share a project and your scripts go along. Load as many as you like; they all stack up in the list.

Structure

A script is a list of plain-text lines. Blank lines and anything after a # are ignored (comments).

Variables you set in :init keep their values between frames, so :render can move things along a little each time — that's how animation works.

The matrix & colour

The matrix is a grid of pixels. (0, 0) is the top-left; x goes right, y goes down. The size is always available as matrix_x (width) and matrix_y (height) — write to those instead of hard-coding a size, and your script works on any wall.

Colours are three numbers — red, green, blue, each 0–255. So 255, 0, 0 is red and 255, 255, 255 is white.

Variables & arrays

Just assign to create a variable — no declarations. Numbers can be whole or decimal.

count = 0
angle = 3.14
count = count + 1

Arrays use square brackets and grow as needed (index from 0):

red[0] = 255
red[1] = 0
x[i] = x[i] + speed[i]

config settings

Use config in :init to declare a named value with a sensible default:

:init
    config dot_count = 100
    config speed = 2
end

It behaves like a normal variable you can read anywhere. (Per-script sliders for these are on the roadmap; for now they run at their default, and the effect's global Speed, Auto-colour speed and Brightness controls sit on top.)

Loops & conditions

Repeat a fixed number of times — for … next

for i = 0 to dot_count step 1
    pset i, 0, 255, 255, 255
next

step is optional (defaults to 1) and can be negative to count down.

Repeat while true — while … wend

i = 0
while i < w
    pset i, i, 0, 255, 0
    i = i + 1
wend

Make decisions — if … else … endif

if x > w
    x = 0
else if x < 0
    x = w
endif

Use & (and) and | (or) to combine conditions: if x > 0 & x < w. A trailing then is allowed but optional.

Subroutines — gosub

Give a block a label, jump to it with gosub, and come back with return:

:render
    gosub new_dot
end

:new_dot
    px = rnd(matrix_x)
    py = rnd(matrix_y)
    return

Operators & maths

Note = does double duty: x = 5 assigns, but inside an if it means "equals".

Drawing commands

Built-in values

Functions

Worked examples

A dot bouncing around

:init
    x = 5
    y = 5
    dx = 1
    dy = 1
end

:render
    fade 40                       # leave a fading trail
    x = x + dx
    y = y + dy
    if x <= 0 | x >= matrix_x - 1
        dx = 0 - dx                 # bounce off the sides
    endif
    if y <= 0 | y >= matrix_y - 1
        dy = 0 - dy
    endif
    pset x, y, autocolor_red, autocolor_green, autocolor_blue
end

A rainbow sweep

:render
    for x = 0 to matrix_x - 1
        hue = x * 360 / matrix_x + frame_count * 4
        hsv2rgb hue, 255, 255, r, g, b
        for y = 0 to matrix_y - 1
            pset x, y, r, g, b
        next
    next
end

Tips & performance

The live editor (Edit script) checks your script as you type and shows the exact line of any problem. Experiment freely — a built-in preset opens as an editable copy, so you can never break the originals.