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.

Request files

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

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), then the payload. A JSON message is always sent first and the matching binary message immediately after, on the same connection; the client pairs them by arrival order. 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.

A session example, client side:

→ {"type":"previewMaterial","sourceFile":"…/M_Sample.dsm","mesh":"shaderball",
   "width":512,"height":512,"requestId":"8f3c1b","stream":true,"frameRate":12}
← [len][1] {"type":"previewResult","requestId":"8f3c1b","status":"ready", … "imagePath":"…"}
← [len][2] <PNG bytes>
← [len][1] {"type":"previewFrame","requestId":"8f3c1b","frameIndex":0, …}
← [len][2] <PNG bytes>
→ {"type":"previewControl","requestId":"8f3c1b","ackFrameIndex":0,"frameRate":12,"orbitYaw":-140.0}
← [len][1] {"type":"previewFrame","requestId":"8f3c1b","frameIndex":1, …}
← [len][2] <PNG bytes>

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