Quickstart: your first preset

1. Find your preset directory (see Where preset files live). On Windows that is %APPDATA%\Ritmolux\presets. Both the standalone app and the foobar2000 plugin read this same folder — it is seeded with the curated set on first run.

2. Copy an existing preset as a starting point. swarm_braid.toml (a calm particle swarm) and fragment_whorl.toml (a slow warp field) are the friendliest bases:

   copy swarm_braid.toml   my_first.toml

3. Edit the bindings. Open my_first.toml and change an expression — for example make the beat kick harder:

   system = "swarm"
   name   = "My First"
   
   [params]
   force      = "1.2 + clamp(bass * 20, 0, 4)"
   spin       = "0.3 + clamp(mid * 6, 0, 1.2)"
   burst      = "beat * 9"          # was beat * 5 — a bigger blast on each beat
   hue        = "time * 0.02 + clamp(treb * 4, 0, 1)"
   brightness = "0.6 + clamp(bass * 6, 0, 0.8)"
   size       = "1.0 + beat * 0.6"

4. Save and watch. The standalone app polls the folder every ~150 ms and hot-reloads on any change (no restart). Press Space to cycle to your new preset, or Tab to pick it by name; the window title shows the active preset name and system. If the file has a typo, the app reports it and keeps the last good set — it never crashes on a bad preset.

   In the foobar2000 component the same loop is one click longer, because it has no watcher: right-click → Reload presets, then right-click → Preset ▸ and pick yours. A file with a typo is simply absent from that list.

That is the whole loop: copy, edit an expression, save, pick.

Check it before you render it

ritmolux --check my_first.toml runs the engine’s own loader over the file and prints what it found, without opening a window or a GPU adapter:

my_first.toml:12:1: error[engine]: parameter 'burst' has an invalid expression: unexpected end of expression
my_first.toml:1:1: warning[engine]: unknown parameter 'wrap' for system 'swarm' (binding kept, but nothing reads it)

It answers in one process start, which makes it the first thing to reach for and shot the second: a render tells you how a preset looks, and this tells you whether it compiles at all. Point it at a directory to check every preset in it. --strict makes a warning cost an exit code too, which is what a gate wants and what you do not while you are still editing. Errors exit 1, a wrong command exits 2, and nothing is ever written — the project has no TOML formatter, on purpose (ADR-0190).

Alongside the loader’s verdict it applies a short list of house-style rules, all warnings, each named by a rule id so you can tell them apart from the engine’s: file-name (a library file’s prefix is its system’s family — collage_ for shape_collage — which is also what gives it that system’s completions in the editor), header-comment (a preset opens by saying what it is), hex-case (a #rrggbb colour is lowercase), and trailing-whitespace, final-newline and tab. The last three are what .editorconfig asks your editor for, so an editor that honours it cannot produce them.

Every preset in the repository is held to all of this by the test run, so a preset landing in the curated set has already passed what you just ran.

---