Functional effects guide (.mjs)

This guide is for anyone who wants to build JavaScript module effects that run when the user selects Effect lighting mode — including beginners who are comfortable with basic JavaScript but may not want a full <canvas> pipeline.

Start below with what an .mjs effect is, then copy the minimal example. For the formal API rules (Worker readiness, enumeration order), see EFFECT-FUNCTIONAL-MJS-CONTRACT.md.

HTML canvas effects (iframe, requestAnimationFrame, engine, <meta property>) are documented in EFFECT-DEVELOPER-GUIDE.md.

For downloads, Effect Builder, and gallery publishing, see rgbjunkie.com.

Making functional effects (start here)

What you are writing

A single ES module file (extension .mjs) that exports exactly two named bindings:

There is no canvas and no animation loop inside your module. The host drives time by passing args.tSec and args.frameIndex. Your job is pure math: “given this LED, this time, and the user’s settings, what RGB?”

Why the host does it this way

The app needs colors for many LEDs per frame. A functional effect is easy for the host to run in lockstep with hardware sampling and workspace previews: it is just a function. That also keeps effects small and testable compared to a full HTML scene graph.

HTML vs functional — quick choice

Use HTML when you want layouts, images, screen capture, or rich UI. Use .mjs when your effect is pure lighting math and you want a single file with predictable performance.

Minimal example (copy and adapt)

Save as something like effects/MyFirstSweep.mjs (or your user effects folder — same discovery rules as HTML files). The basename should be unique vs any .html in the same folder.

/**
 * SPDX-License-Identifier: LicenseRef-RGBJunkie-Proprietary
 * (Use your own SPDX / copyright line for shipping effects.)
 */

export const meta = {
    id: "my_first_sweep",
    name: "My First Sweep",
    description: "A hue that travels along the strip using host time.",
    publisher: "Your Name",
    contractVersion: 1,
    params: [
        { key: "speed", label: "Speed", type: "number", min: 1, max: 200, default: 80 },
    ],
};

function hueToRgb(p, q, t) {
    let tt = t;
    if (tt < 0) tt += 1;
    if (tt > 1) tt -= 1;
    if (tt < 1 / 6) return p + (q - p) * 6 * tt;
    if (tt < 1 / 2) return q;
    if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
    return p;
}

function hslToRgb(h, s, l) {
    if (s === 0) {
        const v = Math.round(l * 255);
        return { r: v, g: v, b: v };
    }
    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
    const p = 2 * l - q;
    const r = hueToRgb(p, q, h + 1 / 3);
    const g = hueToRgb(p, q, h);
    const b = hueToRgb(p, q, h - 1 / 3);
    return {
        r: Math.round(Math.max(0, Math.min(255, r * 255))),
        g: Math.round(Math.max(0, Math.min(255, g * 255))),
        b: Math.round(Math.max(0, Math.min(255, b * 255))),
    };
}

export function sampleLed(args) {
    const speed = Number(args.params.speed ?? 80);
    const n = Math.max(1, args.ledCount - 1);
    const su = args.stripU;
    const u =
        typeof su === "number" && Number.isFinite(su)
            ? Math.max(0, Math.min(1, su))
            : n <= 0
              ? 0.5
              : args.ledIndex / n;
    const phase = (args.tSec * speed * 0.012 + u) % 1;
    return hslToRgb(phase, 0.85, 0.55);
}

What to notice

• meta.id must stay stable (profiles and workspace tabs reference it). Use lowercase, digits, and underscores.
• stripU is 0…1 along the strip when the host can derive it; otherwise fall back to ledIndex / (ledCount - 1).
• args.params.speed is always the types you declared (number → coerced number in the host).

Discovery metadata (meta)

These fields feed the effect browser (search, cards) and the Effects sidebar.

Sidebar controls (meta.params[])

Each control is an object with at least key and type. Optional label, default, min, max, values, allowNone.

For colorProfile, optional allowNone: true matches HTML’s allowNone="true" on <meta type="colorProfile"> (adds None to the list). Omit allowNone for the default list (Custom, Rainbow, built-ins, user profiles).

The sampleLed function

Arguments (args)

Return value

Return { r, g, b }. The host clamps to 0…255 and floors to integers; still prefer clean values.

Performance

The host may call sampleLed very often (every LED × preview grid). Keep inner loops cheap; prefer closed-form math over allocations.

Host context (args.context)

Audio (args.context.audio)

Same information as window.engine.audio for HTML effects:

Mono fallback (recommended):

const a = args.context && args.context.audio;
const stereo =
  a &&
  a.stereo &&
  Array.isArray(a.freqL) &&
  Array.isArray(a.freqR) &&
  a.freqL.length === a.freq?.length &&
  a.freqR.length === a.freq?.length;
const left = stereo ? a.freqL : a?.freq;
const right = stereo ? a.freqR : a?.freq;

When stereo is false, drive both halves of a split layout from freq so mono music stays balanced. HTML canvas authors: full reference in EFFECT-DEVELOPER-GUIDE.md Section 6.2 (published Section 6.2).

Always guard: const a = args.context && args.context.audio; if (!a || typeof a !== "object") ….

Color profiles (sampleColorProfile + colorProfiles)

When the host runs functional effects, it injects:

Recommended pattern: compute your effect’s RGB with your usual math, then tint using the profile so hues stay inside the user’s palette. The built-in *effects/.mjs effects use luminance scaling: compute Rec. 601 luma y from your RGB, then tone = sampleColorProfile(id, paletteT01) and output { r: tone.r y, … }* clamped. That avoids “green × orange still looks green” that you get from naive per-channel multiply.

Declare a control:

{ key: "colorProfile", label: "Color profile", type: "colorProfile", default: "Rainbow" },

…and read String(args.params.colorProfile ?? "Rainbow") when calling sampleColorProfile.

Rules that matter

1. sampleLed must stay pure — no window, document, fetch, localStorage, timers, or DOM. The host may evaluate calls from different code paths; side effects break previews and future Worker offloading.
   Formal list: [EFFECT-FUNCTIONAL-MJS-CONTRACT.md Section 4.2.

1. One module file — no import of other project files unless your bundler supplies them; stock RGBJunkie loads a single .mjs source string. Pure math helpers in the same file are ideal.

1. Multi-workspace tabs use the same snapshot model as HTML effects for params and lighting mode. Overview: EFFECT-MULTI-CANVAS-CONTRACT.md.

Learn more in this repo

Document history