VSCode and Rider

DreamShaderLang ships as two independent products: the Unreal plugin, and a language extension for your editor. They never call each other directly — they exchange files under <Project>/Saved/DreamShader/Bridge/ and one loopback WebSocket. Knowing which side owns what saves a lot of time when something does not work.

Which side implements what

The extensions

Neither extension ships inside the plugin. Install one separately.

The release workflow attaches the latest VSCode extension assets to each plugin GitHub release, so the two versions stay roughly in step. Extension-side settings — a project-root override, a preview frame rate, package store index URLs — are declared by the extension, not by UDreamShaderSettings, and the extension's own repository is authoritative for them.

The generated workspace

Tools ▸ DreamShader ▸ Open Dream Shader Workspace (VSCode) — and the toolbar button of the same name — writes one file and launches an editor on it. since 1.2.1

The source directory is created if it does not exist. The whole file:

{
	"folders": [
		{
			"name": "DreamShader Source",
			"path": "."
		}
	],
	"settings": {
		"files.associations": {
			"*.dsm": "dreamshaderlang",
			"*.dsh": "dreamshaderlang",
			"*.dsf": "dreamshaderlang"
		}
	}
}

Every key the writer emits. There are no others, and nothing is conditional.

What the command does, in order

Steps 1–3 rewrite the same three manifests the bridge writes at editor startup, so an extension installed a minute ago sees current data without an editor restart. See Bridge artifacts.

Launch fallback chain

The first mechanism that succeeds wins; the rest are not attempted.

VSCode executable discovery

Probed in this exact order. Only paths that exist as files are kept, and duplicates are dropped.

Which launcher an action uses

The file launcher clamps line and column to 1 or greater, and its own fallback chain is VSCode → shell default application (Edit verb) → Notepad, the same shape as the workspace chain.

Diagnostics

Toast text and log text differ; both are listed. Runtime substitutions are written {Placeholder}.

What an extension consumes

Every artifact an extension reads or writes lives under <Project>/Saved/DreamShader/Bridge/, plus the loopback WebSocket endpoint.

Is the editor alive?

A client's only way to guess whether an editor was running used to be looking for bridge.db and hoping. The bridge now rewrites status.json every 2 s and deletes it on shutdown — so a missing file means "not running", definitively, and a client can fall back immediately instead of waiting out a liveness window.

Request files

The filename is irrelevant; only the JSON contents matter. action and scope are both matched case-insensitively.

A request carrying a requestId is answered in Responses/<requestId>.json since 1.6.0, with protocol, requestId, ok, durationMs, message and diagnostics. It is written atomically — beside the target, then renamed — so appearing and being complete are the same event; stale responses from a previous session are deleted at startup.

A request may carry protocol. A missing field is read as the current version, not as a mismatch — every request the shipped VSCode extension sends omits it, and rejecting those would break it on every machine that has it installed. A field that is present and different is refused:

Protocol 3 is not understood; this editor speaks 1. Update the DreamShaderLang extension or the
plugin so the two match.

Compilation through this path is always in-memory; a queued file compiles after the debounce window (Save Debounce Seconds, clamped to [0.05, 10.0], default 0.25) plus up to 0.1 s of poll delay, and only if it still exists on disk.

Diagnostics the extension reads

diagnostics.json has the shape { "version": 1, "updatedAtUtc": "…", "files": [ { "path": "…", "diagnostics": [ … ] } ] }. Optional fields are omitted entirely when empty.

Locations are recovered from messages shaped <path>(<line>,<column>): <message>; a line with no parseable location is reported at 1,1. Material-compile diagnostics carry a display message of the form [{ShaderPlatform} / {QualityLevel}] {Message}. Since UE 5.7 shaderPlatform carries a shader-format name such as PCD3D_SM6; below 5.7 it carries a feature-level name such as SM6.

Streaming preview

The preview panel connects to ws://127.0.0.1:17864 and drives the plugin's renderer.

Every outbound message is a WebSocket binary frame whose payload is a 4-byte little-endian length, a 1-byte type tag (1 = UTF-8 JSON, 2 = raw PNG, 3 = raw RGBA8 frame since 1.7.0), then the payload. Inbound messages are plain UTF-8 JSON with no prefix and no tag.

Streaming is both rate-limited and acknowledgement-gated: a new frame starts only when the client has acknowledged the previous one and the frame interval has elapsed.

Graph breakpoints

setProbe hands the editor a Graph line number, and the preview mesh then shows the value bound at that line instead of the finished material — the text analogue of the Material Editor's right-click Start Previewing Node. A breakpoint on a blank or comment line snaps forward to the next line that binds a value; one set before the source has ever generated is remembered as pending and attaches on the next compile; after a recompile the probe re-resolves automatically and probeState tells the client the line it landed on. The line is also echoed per frame in the tag-3 frame header. The semantics are on Editor Tools.

A session example, client side:

→ {"type":"previewMaterial","sourceFile":"…/M_Sample.dsm","mesh":"shaderball",
   "width":512,"height":512,"requestId":"8f3c1b","stream":true,"frameRate":12,
   "encoding":"raw"}
← [len][1] {"type":"previewResult","requestId":"8f3c1b","status":"ready", … }
← [len][3] <24-byte header><RGBA8 pixels>
→ {"type":"previewControl","requestId":"8f3c1b","ackFrameIndex":0,"orbitYaw":-140.0}
← [len][3] <24-byte header><RGBA8 pixels>
→ {"type":"setProbe","requestId":"8f3c1b","line":31}
← [len][1] {"type":"probeState","requestId":"8f3c1b","state":"attached","line":31}
← [len][3] <24-byte header><RGBA8 pixels>      // now showing the value bound on line 31

The renderer's own limits — .dsm only, the size clamp, the mesh fallback, the missing pitch clamp — are on Editor Tools.

VSCode commands

Names are the extension's, not the plugin's, and are surfaced under the DreamShaderLang group.

DreamShaderLang: Recompile Current Source
DreamShaderLang: Recompile All Sources
DreamShaderLang: Clean Generated Shaders
DreamShaderLang: Show Bridge Panel
DreamShaderLang: Refresh Bridge Diagnostics
DreamShaderLang: Show Material Preview
DreamShaderLang: Install Package from GitHub
DreamShaderLang: Browse Package Store
DreamShaderLang: Update Installed Packages
DreamShaderLang: Remove Installed Package
DreamShaderLang: Open Packages Folder
DreamShaderLang: Add Package Store Index Source
DreamShaderLang: Remove Package Store Index Source
DreamShaderLang: Create Package Step by Step
DreamShaderLang: Create DreamShader Material
DreamShaderLang: Create DreamShader Function File
DreamShaderLang: Create DreamShader Header
DreamShaderLang: Create DreamShader Texture Sample
DreamShaderLang: Create DreamShader Noise Material

VSCode settings

Extension-declared, so the extension repository is authoritative. Keep the workspace pointed at the Unreal project root — or set dreamshader.projectRoot — so the extension can resolve DShader, DShader/Packages and Saved/DreamShader/Bridge.

{
  "dreamshader.packageStoreIndexUrls": [
    "https://raw.githubusercontent.com/TypeDreamMoon/dreamshader-package-index/main/packages.json"
  ],
  "dreamshader.enableGitHubPackageSearch": true
}

Notes

• The plugin's previewWebSocketPort counterpart is not configurable: the server always binds 127.0.0.1:17864, and a connection from any other address is refused. Two editors on one machine cannot both serve previews — the second logs a listen warning and runs without streaming.
• Diagnostics reported for an imported header map back to the file you actually edited: import lines are replaced by blank lines and each inlined file is bracketed with source markers, so line and column stay put.
• The Material Content Browser's Gen page shows only the first diagnostic per file. The extension shows all of them. See Editor Tools.

Example

Running Tools ▸ DreamShader ▸ Open Dream Shader Workspace (VSCode) on a default project touches:

<Project>/DShader/DreamShader.code-workspace                    rewritten
<Project>/Saved/DreamShader/Bridge/material-expressions.json    rewritten
<Project>/Saved/DreamShader/Bridge/settings.json                rewritten
<Project>/Saved/DreamShader/Bridge/substrate-builtins.json      rewritten
<Project>/Saved/DreamShader/Bridge/bridge.db                    tables replaced

and then launches, for a code.cmd candidate with Open In New Window at its default:

%ComSpec% /C ""C:/Users/<user>/AppData/Local/Programs/Microsoft VS Code/bin/code.cmd"  "C:/Projects/MyGame/DShader/DreamShader.code-workspace""

Asking a running editor to recompile one file, without VSCode:

$req = @{ action = "recompile"; scope = "file"; sourceFile = "C:/Projects/MyGame/DShader/Materials/M_Sample.dsm" }
$dir = "C:\Projects\MyGame\Saved\DreamShader\Bridge\Requests"
$tmp = Join-Path $env:TEMP ("ds-" + [guid]::NewGuid() + ".json")
$req | ConvertTo-Json | Set-Content -Path $tmp -Encoding utf8
Move-Item $tmp (Join-Path $dir ([IO.Path]::GetFileName($tmp)))

Where next