Editing presets in VS Code

Install Even Better TOML (tamasfe.even-better-toml). That is the whole setup: a committed .taplo.toml at the repository root tells the extension which schema each preset file gets, with nothing per-user to configure.

Which schema a file gets depends on its name. A library file — one directly in presets/, presets/proposed/ or presets/pending/ — named for its system’s family (fragment_*.toml for fragment_field, collage_*.toml for shape_collage, curve_*.toml for parametric_curve) gets that system’s own schema from presets/schema/. Inside it you get:

• completion on [params] keys, offering that system’s parameters and the compositing stages’, and not another system’s;
• hover documentation on a parameter — what it does, its default, its typical range and its kind;
• a Problems entry naming a key the system does not accept, which is the mistake the loader deliberately forgives (an unknown parameter is a warning and the binding is kept, ADR-0020). The underline sits on the [params] header rather than on the key itself, so read the Problems panel for the name;
• the closed rosters as a dropdown on [curve] family, [spectrum] layout and every other key drawn from a fixed set.

Everything else gets validation only, from the generic presets/preset.schema.json: the teaching files under docs/examples/, and a library file named off its family. Those still get an entry for an unknown key, but no parameter completion and no parameter hover. So does every [layer], in any file: a layer names its own system, and a per-system schema does not narrow the layer’s [params]. ritmolux --check warns (file-name) on a library file named off its family, which is exactly the file that would lose completion.

All sixteen files — the generic schema, the fourteen per-system schemas and .taplo.toml itself — are generated from the engine’s own ParamSpec, TableDesc and SystemKind declarations, and core/tests/suite/preset_schema.rs fails if any of them is stale or presets/schema/ holds a file no system renders. The same test file holds a seventeenth file from the same export to it: docs/specs/player-schema.json, the document ritmolux --schema prints, which the studio’s schema walks read when no player is built. One command regenerates all of them, and removes a schema left behind by a system that no longer exists:

RLX_UPDATE_PRESET_SCHEMA=1 cargo nextest run -p rlx-core --test suite preset_schema::

The same shape holds the interface’s look (ADR-0252). studio/renderer/tokens.css, the studio’s colour, type, spacing and motion custom properties, is generated from the theme table in core/src/render/theme.rs, which every engine-drawn surface also reads. core/tests/suite/ui_tokens.rs fails when the committed file differs from what the table renders. To change a colour anywhere, change it in the table and regenerate:

RLX_UPDATE_UI_TOKENS=1 cargo nextest run -p rlx-core --test suite ui_tokens::

Never hand-edit tokens.css: that is exactly the edit the test fails on.

Turn format-on-save off for TOML. The extension ships a formatter, and this project does not format TOML: the presets carry deliberate local alignment that every formatter measured against them destroyed (ADR-0190). .taplo.toml carries no [formatting] table, but that cannot stop your editor’s own format-on-save, so if you have it on globally, exclude TOML in your settings:

"[toml]": { "editor.formatOnSave": false }

Without that, one save reflows the file and the diff touches every line. .vscode/ is gitignored, so this lives in your own settings rather than in the repository.

Optionally, a task that runs the checker on the open file. In .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "check preset",
      "type": "shell",
      "command": "cargo run -q -p standalone --bin ritmolux -- --check ${file}",
      "problemMatcher": {
        "owner": "ritmolux",
        "fileLocation": ["absolute"],
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+): (error|warning)\\[([^\\]]+)\\]: (.*)$",
          "file": 1, "line": 2, "column": 3, "severity": 4, "code": 5, "message": 6
        }
      }
    }
  ]
}

That gives the checker’s diagnostics in the Problems panel. The schema and the checker cover different things and both are worth having: the schema knows every name and roster and underlines live, and only --check compiles an expression. See the preset authoring guide for what it reports.