Extensions: make it your own app
Add your own effects and drawing tools to Starlight with one small JavaScript file per extension.
An extension is a file at <project>/extensions/<name>/index.js. It exports one function, export default function register(api), and imports nothing. Everything it needs comes in the api object. When you save the file, Starlight loads the new version at once.
- Only
index.jsloads. Put all of the extension's code in that one file. Starlight skips a folder without anindex.js. - The folder name is the extension's name. It shows in error lines and in the trust prompt.
- The names you register (for example with
registerEffect) are what scenes use. One extension can register more than one effect or node type. - The optional file
extensions/manifest.jsonlists extensions with a name, a kind and a description. Extensions in it load first, in its order. The other folders load after them, in alphabetical order. - A project's extensions run only after you trust them (Trust a project's extensions).
What you can register
An extension can add three kinds of things. The built-in effects use the same plugin API.
- Effects. A GPU shader that changes a layer's pixels: a grade, a style, a distortion. You write the same maths twice: in GLSL for WebGL2 and in WGSL for WebGPU. You also list its number params. It works in scene YAML and in the effect picker as soon as it loads.
- Colour ops. A function that turns one colour into another. Starlight adds it to the layer's one colour lookup table (LUT), so it costs almost nothing.
- Node types. A new kind of drawing, for example a score bar or a badge. You build it with the Pixi tools in
api.pixi.
If an extension fails with an error, Starlight shows a one-line message on the canvas and skips that extension. The app keeps working. Starlight also removes anything that the extension registered before the error.
If you register a name that already exists, your version replaces the old one. So an extension that registers blur replaces the built-in blur while it is loaded. The picker still lists it with the built-in effects.
A new node type loads and shows in the catalog and the command palette. In the scene file, you write it with the node: keyword. Its own settings sit beside it, at the same indent:
- transform:
- node: badge # the name the extension registered
size: 120 # the extension's own settings
fill: "#ff0000"
position: { x: 400, y: 200 }
The common fields (id, clock, effects, blend, bypass, span, delay) work as on any layer. Every other key belongs to the extension, and Starlight keeps it as it is.
A scene that holds a custom node is saved as schemaVersion: 6. It opens and saves without the extension, but the node draws only while the extension is loaded and trusted. You cannot write a built-in type this way: node: text is an error, so use text:.
The injected api
These are all the tools an extension gets.
| Member | What it does |
|---|---|
registerEffect(name, def) | Adds a GPU effect or a colour op. name is its YAML keyword and its name in the catalog. |
defineShaderEffect(spec) | The easy way to build an effect. Give it the two shader bodies and a list of number params. Pass the result to registerEffect. |
definePointOp(compile) | Builds a colour op. compile(params) runs once per LUT build and returns (rgb) => void. |
registerNodeType(kind, def) | Adds a node type. def.build(ctx, node) returns a Pixi Container. |
pixi | The Pixi tools for node types: { Container, Graphics, Sprite, Text, TextStyle }. They are the only Pixi parts you can use. |
z | A small schema helper, because extensions cannot import zod: z.number/string/boolean/enum/object, each with .optional(). It only describes the params: Starlight does not check values against it. |
EASING_PRESETS | The curve eases as bezier points: linear, ease, ease-in, ease-out, ease-in-out, smooth, snap, overshoot, expo-in, expo-out, expo-in-out, back-in, back-in-out. |
The shader contract
These rules connect your params to the shader code.
Each param becomes one float uniform. Its name is u plus the param name with a capital first letter: gap → uGap, amount → uAmount, rHi → uRHi.
defineShaderEffect makes only float uniforms, so there is no colour param type. Pass a team colour as three floats, r, g and b, each from 0 to 1 (see the duotone below). If you pass a colour string, Starlight ignores it and uses the default.
| GLSL (WebGL2) | WGSL (WebGPU) | Meaning |
|---|---|---|
| texture(uTexture, vTextureCoord) | textureSample(uTexture, uSampler, uv) | read the input pixels |
| vTextureCoord | uv | the current pixel's UV |
| uInputSize.xy / .zw | gfu.uInputSize.xy / .zw | (w, h) in px / (1/w, 1/h), one pixel's size |
| u<Param> | fx.u<Param> | your float params |
| finalColor = … | return vec4<f32>(…) | write or return the result |
Animate a param. Mark it animatable: true. Then it accepts a keyframe list, for example { amount: [0, 1, 0] }. The keyframes follow the layer's clock, or the effect's own clock:.
Declare reach if you read other pixels. Some shaders read pixels next to the one they write: a displacement, a cell snap, a blur. Add reach: how far it reads, in px, as a number or (params) => px.
Export renders very wide surfaces in strips. An effect without reach shows a seam at each strip edge.
In WGSL, the global filter values are on gfu: uInputSize, uInputPixel, uInputClamp, uOutputFrame, uGlobalFrame and uOutputTexture. Your params are on fx.
Example: the scanlines extension that comes with the demo project (demo-project/extensions/scanlines/index.js).
export default function register(api) {
api.registerEffect('scanlines', api.defineShaderEffect({
name: 'scanlines',
params: [
{ name: 'gap', default: 3, animatable: true }, // → uGap
{ name: 'opacity', default: 0.35, animatable: true }, // → uOpacity
],
glsl: `
vec4 c = texture(uTexture, vTextureCoord); // read input
float row = vTextureCoord.y * uInputSize.y; // height in px
float line = mod(floor(row / max(uGap, 1.0)), 2.0); // 0 or 1 per row
finalColor = vec4(c.rgb * (1.0 - line * uOpacity), c.a);
`,
wgsl: `
let c = textureSample(uTexture, uSampler, uv);
let row = uv.y * gfu.uInputSize.y;
let line = f32(i32(floor(row / max(fx.uGap, 1.0))) % 2);
return vec4<f32>(c.rgb * (1.0 - line * fx.uOpacity), c.a);
`,
}));
}
Example effects
Each example is the inside of register(api), with the YAML that uses it.
Team-colour duotone grade
Maps the image's brightness from a shadow colour to a highlight colour. Use it to give all your footage the team look.
api.registerEffect('duotone', api.defineShaderEffect({
name: 'duotone',
params: [
{ name: 'rShadow', default: 0.04 }, { name: 'gShadow', default: 0.05 }, { name: 'bShadow', default: 0.12 },
{ name: 'rHi', default: 1.0 }, { name: 'gHi', default: 0.80 }, { name: 'bHi', default: 0.0 },
{ name: 'amount', default: 1.0, animatable: true },
],
glsl: `
vec4 base = texture(uTexture, vTextureCoord);
float lum = dot(base.rgb, vec3(0.299, 0.587, 0.114));
vec3 duo = mix(vec3(uRShadow,uGShadow,uBShadow), vec3(uRHi,uGHi,uBHi), lum);
finalColor = vec4(mix(base.rgb, duo, uAmount), base.a);
`,
wgsl: `
let base = textureSample(uTexture, uSampler, uv);
let lum = dot(base.rgb, vec3<f32>(0.299, 0.587, 0.114));
let duo = mix(vec3<f32>(fx.uRShadow,fx.uGShadow,fx.uBShadow), vec3<f32>(fx.uRHi,fx.uGHi,fx.uBHi), lum);
return vec4<f32>(mix(base.rgb, duo, fx.uAmount), base.a);
`,
}));
effects:
- duotone: { rHi: 0.98, gHi: 0.74, bHi: 0.0, amount: 1 } # gold highlights
LED-panel look
Snaps the picture to a grid of cells and darkens the gaps, so any content looks like it belongs on the LED wall. It reads each cell's centre, so it declares a reach.
api.registerEffect('led-grid', api.defineShaderEffect({
name: 'led-grid',
params: [{ name: 'size', default: 10, animatable: true }, { name: 'gap', default: 0.15 }],
reach: (p) => Math.max(p.size, 2), // reads up to a cell away
glsl: `
float cell = max(uSize, 2.0);
vec2 px = uInputSize.zw; vec2 pos = vTextureCoord / px;
vec2 center = (floor(pos / cell) + 0.5) * cell * px;
vec4 c = texture(uTexture, center);
vec2 f = fract(pos / cell);
float d = min(min(f.x, 1.0 - f.x), min(f.y, 1.0 - f.y));
finalColor = vec4(c.rgb * smoothstep(0.0, uGap, d), c.a);
`,
wgsl: `
let cell = max(fx.uSize, 2.0);
let px = gfu.uInputSize.zw; let pos = uv / px;
let center = (floor(pos / cell) + vec2<f32>(0.5)) * cell * px;
let c = textureSample(uTexture, uSampler, center);
let f = fract(pos / cell);
let d = min(min(f.x, 1.0 - f.x), min(f.y, 1.0 - f.y));
return vec4<f32>(c.rgb * smoothstep(0.0, fx.uGap, d), c.a);
`,
}));
effects:
- led-grid: { size: 12, gap: 0.18 }
Vignette
Darkens the edges, with the correct shape for any surface size. It pulls the eye to the centre of the surface.
api.registerEffect('vignette', api.defineShaderEffect({
name: 'vignette',
params: [{ name: 'amount', default: 0.6, animatable: true }, { name: 'radius', default: 0.35 }, { name: 'softness', default: 0.35 }],
glsl: `
vec4 c = texture(uTexture, vTextureCoord);
vec2 p = vTextureCoord - 0.5; p.x *= uInputSize.x / uInputSize.y;
float v = 1.0 - smoothstep(uRadius, uRadius + uSoftness, length(p)) * uAmount;
finalColor = vec4(c.rgb * v, c.a);
`,
wgsl: `
let c = textureSample(uTexture, uSampler, uv);
var p = uv - vec2<f32>(0.5); p.x = p.x * (gfu.uInputSize.x / gfu.uInputSize.y);
let v = 1.0 - smoothstep(fx.uRadius, fx.uRadius + fx.uSoftness, length(p)) * fx.uAmount;
return vec4<f32>(c.rgb * v, c.a);
`,
}));
Wave displacement (animated)
A sideways sine wave, like a flag in the wind or hot air. Animate phase from 0 to 1 to make the wave travel. It reads amp px to the side, so that is its reach.
api.registerEffect('wave', api.defineShaderEffect({
name: 'wave',
params: [{ name: 'amp', default: 6 }, { name: 'freq', default: 40 }, { name: 'phase', default: 0, animatable: true }],
reach: (p) => Math.abs(p.amp),
glsl: `
vec2 p = vTextureCoord;
p.x += sin(p.y * uFreq + uPhase * 6.2831853) * uAmp * uInputSize.z;
finalColor = texture(uTexture, p);
`,
wgsl: `
var p = uv;
p.x = p.x + sin(p.y * fx.uFreq + fx.uPhase * 6.2831853) * fx.uAmp * gfu.uInputSize.z;
return textureSample(uTexture, uSampler, p);
`,
}));
effects:
- wave: { amp: 8, freq: 36, phase: [0, 1], clock: { period: 1200ms } }
Colour key to transparent
Makes pixels near one colour transparent. Use it to put a green-screen sponsor clip over the surface.
api.registerEffect('color-key', api.defineShaderEffect({
name: 'color-key',
params: [
{ name: 'rKey', default: 0.0 }, { name: 'gKey', default: 1.0 }, { name: 'bKey', default: 0.0 },
{ name: 'tol', default: 0.30, animatable: true }, { name: 'soft', default: 0.10 },
],
glsl: `
vec4 c = texture(uTexture, vTextureCoord);
float a = smoothstep(uTol, uTol + uSoft, distance(c.rgb, vec3(uRKey,uGKey,uBKey)));
finalColor = vec4(c.rgb, c.a * a);
`,
wgsl: `
let c = textureSample(uTexture, uSampler, uv);
let a = smoothstep(fx.uTol, fx.uTol + fx.uSoft, distance(c.rgb, vec3<f32>(fx.uRKey,fx.uGKey,fx.uBKey)));
return vec4<f32>(c.rgb, c.a * a);
`,
}));
Write a colour op
A colour op changes one colour at a time. It cannot see other pixels, the position, or the alpha (the transparency).
- Call
registerEffectwith a def that has apointOpand no shader. - Build the
pointOpwithapi.definePointOp, as in the example below. - Save the file. The op joins the layer's one colour LUT, in stack order with the built-in grades.
export default function register(api) {
api.registerEffect('posterize', {
schema: api.z.object({ levels: api.z.number().optional() }),
defaults: { levels: 4 },
animatableParams: ['levels'],
separable: true, // each channel depends only on itself
pointOp: api.definePointOp((p) => {
const n = Math.max(2, p.levels) - 1; // setup: once per bake
return (rgb) => { // per colour, sRGB 0..1, in place
for (let c = 0; c < 3; c++) rgb[c] = Math.round(rgb[c] * n) / n;
};
}),
});
}
- Keep it pure. The same colour and params must give the same result, because Starlight caches the LUT by params. Starlight limits the results to 0..1 for you.
- Set
separable: trueonly when each output channel depends on that same channel alone (levels, curves, invert). It makes the op faster. A wrongtruegives wrong colours. - Need alpha or other pixels? Write a shader effect instead.
- In the picker, an extension's colour op shows in the extensions block. Its card sits in the color group, with the built-in colour ops.
Example node type: a score bar
A new drawing built with api.pixi. It loads and draws, and it saves in the scene file as - node: score-bar (see above).
export default function register(api) {
const { Container, Graphics } = api.pixi;
api.registerNodeType('score-bar', {
schema: api.z.object({ value: api.z.number(), width: api.z.number().optional(), fill: api.z.string().optional() }),
// build(ctx, node) → a Pixi Container. ctx: { assets, surface, design, buildNode, buildChildren, resolveComp, … }
build(ctx, node) {
const w = typeof node.width === 'number' ? node.width : 600, h = 40;
const v = Math.max(0, Math.min(1, node.value ?? 0));
const c = new Container();
c.addChild(new Graphics().roundRect(0,0,w,h,h/2).fill('#1b1b1f')); // track
c.addChild(new Graphics().roundRect(0,0,Math.max(h,w*v),h,h/2).fill(node.fill ?? '#ffcc00')); // fill
return c;
},
});
}
What you could build
Ideas, marked by type. [Effect] and [Colour op] work today. [Node] works too: it saves with the node: keyword.
- A team's own grade: the duotone set to your two colours, on every video. [Effect]
- A house look in one op: posterize, a split tone, or a brand-colour remap. [Colour op]
- Stadium LED look:
led-gridwith a lightglow, so content looks as if it was made for the LED wall. [Effect] - Sponsor chroma-key belt:
color-keyon a green-screen loop, on a drifting clone belt. [Effect] - Retro broadcast package:
halftone,scanlinesandchroma-shifttogether, for a replay in an old TV style. [Effect] - Flag-wave transitions: the
waveeffect across a full-frame graphic. [Effect] - Live-score node, a branded lower-third maker, sport widgets (a down-and-distance chip, pitch-count dots, a shot-clock ring). [Node]
Make one: scaffold, edit, use
Make a new extension from a template, then test it on a surface.
- Scaffold (make a starting template). Ask Claude in the Claude panel (⌃` / Ctrl+`) to make an effect. Or call the MCP tool
scaffold_extension { name, kind, description }, wherekindiseffectornode. You can also make the folder by hand. - The name must be lower-kebab-case and start with a letter, for example
led-scan. Ifindex.jsalready exists, the scaffold refuses and asks you to edit it. - The scaffold writes a working template with TODO marks. The effect template darkens by an
amountparam. The node template draws a square withsizeandfill. - It also records the extension in
extensions/manifest.json. A scaffolded extension is trusted until you quit the app. - Edit
index.js. Keep the GLSL and WGSL maths the same. Save the file, and it loads again. - Check. Open the effect picker in Properties. Your effect is in its extensions block.
get_projectalso lists it, withextension: true. - Use it. Add it from the picker, or in a layer's
effects:list. - Look. Render a still of a surface that uses it (
render_still). Change the shader and look again.
- A load error shows as one red line at the bottom left of the canvas:
extension <name>: <message>. - A syntax error reads
failed to load: …. A file with noregisterfunction readsextension has no default export function register(api). - While an extension is not loaded, Claude cannot write a scene that uses its effect. The write is refused with
unknown effect "…".
Trust a project's extensions
Starlight asks before it runs a project's extensions, because they can do anything the app can do.
- Read the line at the top of the window. It names the extensions: this project runs its own code: led-scan, ticker — extensions get full access to the app. trust them? After three names, it adds +N more.
- Click trust only if you would run this code on your computer.
- Or click not now. The extensions stay off for this session. Starlight says extensions not loaded — trust them later from the palette.
- To answer later, open the command palette (⌘/ / Ctrl+/) and choose trust project extensions…. The prompt line comes back. If nothing is waiting, Starlight says no extensions waiting to be trusted.
- When a trusted extension's file has changed, the line says, for example, led-scan changed since you trusted it — run the new code?
- An extension you have not trusted does not run. Layers that use its effects draw without them.
An extension can do everything the app can do, like an After Effects script. Starlight remembers your trust in its settings, for each project folder and for the exact code. If a file changes, Starlight asks again the next time it loads. The same extension in another folder also asks again.
Extensions you trusted or scaffolded in this session load your edits without asking, until you quit the app. The demo project's scanlines never asks, as long as its file is unchanged.
When an extension misbehaves
Find the symptom, then follow the fix.
| Symptom | Fix |
|---|---|
Not in the effect picker or in get_project |
|
A red line says failed to load | The file has a syntax error. Fix the line it names, and save. |
| Layers that use the effect look plain | The extension is not loaded: it is not trusted yet, or it failed. Check the trust line and the red line on the canvas. |
| It renders wrong, or nothing | The GLSL and WGSL do different maths. Make them the same. Check that uniform names follow u<Capitalized>. |
| A seam in exports of very wide surfaces | The shader reads other pixels but has no reach. Add one. |
| A colour param is ignored | Params are floats only. Pass a colour as three floats, r, g, b (0 to 1). |
| A param does not animate | Write it as a keyframe list, and mark it animatable: true. |
| A new node type does not work in YAML | This is expected for now. See What you can register. |