Make your first Shader Forge plugin

You'll build Neon Pulse, a plugin with three effects (a traveling glow, stripes and a wobble), a preset, an app theme and a one-click command. No build tools are needed: a plugin is one text file.

What you'll have at the end

The "Neon club ball" preset from your own plugin, running in the live preview. Its effects export to Built-in, URP and HDRP like the built-in ones do.

1What a plugin is

A plugin is a single .xsfplugin file. Inside is JSON (the same format as a .json file) that can add any mix of:

2Create the file

1. In Shader Forge, open the Plugins menu in the toolbar and choose Create a new plugin…
2. Type the name Neon Pulse. Shader Forge writes neon-pulse.xsfplugin into your plugin folder and shows it to you.
3. Open the file in any text editor: VS Code, Notepad++ or plain Notepad all work.

The new file already works. It contains a starter effect, a theme and a "Say hello" command, plus a _help list that sums up the rules. Delete what you don't need as you go. Prefer to start from scratch? Download the starter file.

3The top of the file

Every plugin starts with a few fields that say who it is:

{
  "format": "xsf-plugin",
  "formatVersion": 1,
  "id": "you.neon-pulse",
  "name": "Neon Pulse",
  "version": "1.0.0",
  "author": "You",
  "icon": "💡",
  "description": "A pulsing neon glow, stripes, a wobble and a matching theme.",
  "category": { "id": "neon", "label": "Neon Pulse", "icon": "💡" },

  "effects": [],
  "presets": [],
  "themes": []
}

4Your first effect

Add this to the effects list. It makes bands of glow that travel up the model:

{
  "id": "neonPulse",
  "cat": "neon",
  "label": "Neon pulse",
  "desc": "Bands of glow that travel up the model.",
  "params": [
    { "id": "_NpColor",  "label": "Glow color", "type": "color", "hdr": true, "def": [0.2, 1, 0.9, 1] },
    { "id": "_NpSpeed",  "label": "Speed",      "type": "range", "min": 0, "max": 10, "def": 3 },
    { "id": "_NpBands",  "label": "Bands",      "type": "range", "min": 1, "max": 20, "def": 4 },
    { "id": "_NpSharp",  "label": "Sharpness",  "type": "range", "min": 1, "max": 16, "def": 4 },
    { "id": "_NpAmount", "label": "Amount",     "type": "range", "min": 0, "max": 5,  "def": 1.5 }
  ],
  "emit": "float npW = 0.5 + 0.5 * sin(t * _NpSpeed - d.uv.w * _NpBands * 6.2831853);\nemit += _NpColor.rgb * pow(npW, _NpSharp) * _NpAmount;"
}

Save, reload the plugins, and you'll find Neon pulse in a new Neon Pulse category. Here's what each part does:

• params become sliders in Shader Forge and material properties in Unity. Their ids start with _ and must be unique across all effects, so give them a short prefix (_Np… here).
• emit is the stage: the moment in the shader where your code runs. In the emit stage you add light to the emit variable.
• The code is HLSL, Unity's shader language. The line \n in the JSON string is a line break.

Here's the shader code on its own, easier to read:

// 0..1 wave that moves along the mesh's V coordinate over time
float npW = 0.5 + 0.5 * sin(t * _NpSpeed - d.uv.w * _NpBands * 6.2831853);
// sharpen the wave into thin bands and add it as glow
emit += _NpColor.rgb * pow(npW, _NpSharp) * _NpAmount;

5Stages: where your code runs

An effect can put code in one or more stages. They run in this order, per pixel, except vertex, which runs per vertex:

Things you can read

6More kinds of settings

Dropdowns that switch code

An enum can choose between different versions of a stage. Give the stage a switch and one piece of code per option. Only the chosen code ends up in the shader, so it costs nothing on Quest. This is the second Neon Pulse effect:

{
  "id": "neonStripes", "cat": "neon", "label": "Neon stripes",
  "desc": "Painted stripes across or along the model.",
  "params": [
    { "id": "_NsColor", "label": "Stripe color", "type": "color", "def": [1, 0.2, 0.8, 1] },
    { "id": "_NsCount", "label": "Count", "type": "range", "min": 1, "max": 40, "def": 10 },
    { "id": "_NsDir", "label": "Direction", "type": "enum", "options": [["Across", 0], ["Along", 1]], "def": 0 }
  ],
  "surface": {
    "switch": "_NsDir",
    "cases": [
      "float nsS = step(0.5, frac(d.uv.w * _NsCount));\ncol.rgb = lerp(col.rgb, _NsColor.rgb, nsS * _NsColor.a);",
      "float nsS = step(0.5, frac(d.uv.z * _NsCount));\ncol.rgb = lerp(col.rgb, _NsColor.rgb, nsS * _NsColor.a);"
    ]
  }
}

Moving the mesh

The third effect uses the vertex stage to push each vertex along its normal:

{
  "id": "neonWobble", "cat": "neon", "label": "Neon wobble",
  "desc": "The mesh gently wobbles to the beat.",
  "params": [
    { "id": "_NwAmount", "label": "Amount", "type": "range", "min": 0, "max": 0.2, "def": 0.03 },
    { "id": "_NwSpeed",  "label": "Speed",  "type": "range", "min": 0, "max": 20,  "def": 6 }
  ],
  "vertex": "p += nrm * sin(t * _NwSpeed + p.y * 8.0) * _NwAmount;"
}

7Helper functions

Need noise or cells? List the helper in "helpers" and Shader Forge adds its function to the shader, only when your effect is switched on.

"helpers": ["noise", "voronoi"],
"surface": "float lvN = XSFFbm(d.uv.zw * 6.0 + t * 0.2);\nfloat3 lvV = XSFVoronoi(d.uv.zw * 8.0, t);\ncol.rgb *= 0.6 + 0.4 * lvN;"

8Add a preset

A preset is a saved set of settings. Put it in presets. It can use your effects and the built-in ones, and values only needs the settings you want to change.

"presets": [
  {
    "name": "Neon club ball",
    "cat": "Neon Pulse",
    "config": {
      "name": "Neon/ClubBall",
      "lighting": "toon",
      "blend": "opaque",
      "features": { "neonPulse": true, "neonStripes": true },
      "values": { "_Color": [0.08, 0.05, 0.15, 1], "_NpColor": [1, 0.3, 0.9, 1], "_NsColor": [0.2, 0.9, 1, 1], "_NsCount": 16 }
    }
  }
]

9Add an app theme

Themes restyle Shader Forge itself. Each one is a list of CSS colors, and anything you leave out keeps its default.

"themes": [
  {
    "id": "neon-night", "name": "Neon Night", "dark": true,
    "vars": { "--bg": "#0d0b1a", "--panel": "#15122a", "--panel-2": "#1d1938", "--line": "#2d2752",
              "--text": "#f1ecff", "--muted": "#a79fd0", "--accent": "#ff4fd8" }
  }
]

Useful keys: --bg, --panel, --panel-2, --panel-3, --line, --line-2, --text, --muted, --faint, --accent, --preview-bg, --code-bg, --gutter-bg and the code colors --syn-k, --syn-fn, --syn-num, --syn-str, --syn-com. Pick your theme in Settings › Look.

10Add a command (script)

The script field is JavaScript. It runs once when the plugin loads, with an xsf object you use to add commands:

xsf.addCommand({
  label: 'Neon: random glow color',
  icon: '💡',
  run() {
    const c = xsf.getConfig();                 // a copy of the current shader settings
    c.values._NpColor = [Math.random() * 2, Math.random() * 2, Math.random() * 2, 1];
    xsf.setConfig(c);                          // apply them (the user can undo)
    xsf.toast('New glow color!');
  }
});

In the file it's one JSON string. Use \n for new lines:

"script": "xsf.addCommand({ label: 'Neon: random glow color', icon: '💡', run() {\n  const c = xsf.getConfig();\n  c.values._NpColor = [Math.random() * 2, Math.random() * 2, Math.random() * 2, 1];\n  xsf.setConfig(c);\n  xsf.toast('New glow color!');\n} });"

11Test it & fix errors

1. Save the file, then click Reload plugins in the Plugin manager.
2. Look at your plugin in Plugins › Plugin manager. Each plugin shows what it added. If something is wrong, you'll see the error and the exact line of shader code that failed. A broken effect is skipped, and the rest of your plugin still loads.
3. Switch your effects on, move every slider, and try all three pipelines (Built-in / URP / HDRP) at the top.
4. Check the Quest meter. Noise, cells and texture reads cost the most.

12Share it

• In the Plugin manager, click Export next to your plugin to save a copy anywhere.
• Others install it by dragging the .xsfplugin file onto Shader Forge, or with Plugins › Install plugin…
• Shaders made with your effects remember that they need your plugin. When someone opens a shared preset without it, Shader Forge tells them which plugin is missing.
• Bump version each time you share an update.

Want your plugin in the Plugin Store? Submissions open when the store does.

13Try it: plugin maker

Fill this in to generate a working one-effect plugin. Then download it and drag it onto Shader Forge.

Next steps: open the finished Neon Pulse plugin to see everything from this page in one file, or look at the plugins in the store for ideas.